ai-qakit 1.0.0

package/templates/.cursor/rules/problem-solving/references/when-stuck.md

@@ -0,0 +1,72 @@
+# When Stuck - Problem-Solving Dispatch
+
+Different stuck-types need different techniques. Match stuck-symptom to technique.
+
+## Dispatch Flowchart
+
+```
+YOU'RE STUCK
+│
+├─ Complexity spiraling? Same thing 5+ ways? Growing special cases?
+│  └─→ USE: Simplification Cascades
+│
+├─ Can't find fitting approach? Conventional solutions inadequate?
+│  └─→ USE: Collision-Zone Thinking
+│
+├─ Same issue different places? Reinventing wheels? Feels familiar?
+│  └─→ USE: Meta-Pattern Recognition
+│
+├─ Solution feels forced? "Must be done this way"? Stuck on assumptions?
+│  └─→ USE: Inversion Exercise
+│
+├─ Will this work at production? Edge cases unclear? Unsure of limits?
+│  └─→ USE: Scale Game
+│
+└─ Code broken? Wrong behavior? Test failing?
+   └─→ USE: Debugging skill (systematic-debugging)
+```
+
+## Stuck-Type → Technique Map
+
+| How You're Stuck | Symptom Details | Use This |
+|------------------|-----------------|----------|
+| **Complexity spiraling** | Same thing 5+ ways, growing special cases, excessive if/else | simplification-cascades.md |
+| **Need innovation** | Conventional inadequate, can't find fitting approach, need breakthrough | collision-zone-thinking.md |
+| **Recurring patterns** | Same issue different places, reinventing wheels, déjà vu feeling | meta-pattern-recognition.md |
+| **Forced by assumptions** | "Must be done this way", can't question premise, forced solution | inversion-exercise.md |
+| **Scale uncertainty** | Production unclear, edge cases unknown, unsure of limits | scale-game.md |
+| **Code broken** | Wrong behavior, test failing, unexpected output | debugging skill |
+
+## Process
+
+1. **Identify stuck-type** - What symptom matches above?
+2. **Load that technique** - Read the specific reference file
+3. **Apply technique** - Follow its process
+4. **Document attempt** - What worked/failed?
+5. **If still stuck** - Try different technique or combine
+
+## Combining Techniques
+
+Some problems need multiple techniques:
+
+- **Simplification + Meta-pattern** - Find pattern → simplify all instances
+- **Collision + Inversion** - Force metaphor → invert assumptions
+- **Scale + Simplification** - Test extremes → reveal what to eliminate
+- **Meta-pattern + Scale** - Universal pattern → test at extremes
+
+## When Nothing Works
+
+If no technique helps:
+1. **Reframe problem** - Are you solving the right problem?
+2. **Get fresh perspective** - Explain to someone else
+3. **Take break** - Distance often reveals solution
+4. **Simplify scope** - Solve smaller version first
+5. **Question constraints** - Are they real or assumed?
+
+## Remember
+
+- Match symptom to technique
+- One technique at a time
+- Combine if first doesn't work
+- Document what you tried
+- Not stuck forever, just temporarily

package/templates/.cursor/rules/project-manager.mdc

@@ -0,0 +1,116 @@
+---
+description: Project manager for tracking progress and managing tasks
+globs:
+  - "**/plan.md"
+  - "**/phase-*.md"
+  - "**/tasks/**"
+---
+
+# Project Manager
+
+Project manager for tracking progress and managing implementation tasks.
+
+## Responsibilities
+
+1. **Track Progress** - Update status in plan files
+2. **Manage Tasks** - Ensure tasks are completed
+3. **Report Status** - Keep stakeholders informed
+4. **Identify Blockers** - Surface issues early
+
+## Task States
+
+| State | Description |
+|-------|-------------|
+| pending | Not started |
+| in_progress | Currently working |
+| blocked | Waiting on dependency |
+| review | In code review |
+| completed | Done and verified |
+
+## Progress Update Format
+
+### In plan.md
+
+```markdown
+## Phases
+
+| # | Phase | Status | Progress |
+|---|-------|--------|----------|
+| 1 | Setup | completed | 100% |
+| 2 | Core | in_progress | 60% |
+| 3 | Tests | pending | 0% |
+```
+
+### In phase-XX.md
+
+```markdown
+## Status
+- Status: in_progress
+- Progress: 60%
+- Last Updated: 2024-12-06
+
+## Todo List
+- [x] Task 1
+- [x] Task 2
+- [ ] Task 3 (in progress)
+- [ ] Task 4
+- [ ] Task 5
+```
+
+## Status Report Format
+
+```
+════════════════════════════════════════
+📊 PROJECT STATUS: [task-id]
+════════════════════════════════════════
+
+OVERALL: [X]% complete
+
+PHASE 1: Setup ✓
+  Completed: 2024-12-04
+
+PHASE 2: Core (in progress)
+  Progress: 60%
+  Remaining:
+    - [ ] Task 3
+    - [ ] Task 4
+
+PHASE 3: Tests (pending)
+  Blocked by: Phase 2
+
+BLOCKERS:
+  - [blocker description]
+
+NEXT STEPS:
+  - [step 1]
+  - [step 2]
+
+UPDATED: 2024-12-06 14:30
+════════════════════════════════════════
+```
+
+## Update Triggers
+
+Update progress when:
+- Task completed
+- Phase started/finished
+- Blocker encountered
+- Blocker resolved
+- Significant milestone reached
+
+## Reporting Cadence
+
+- **Phase Start**: Initial status
+- **Daily**: Progress update (if active)
+- **Phase End**: Completion summary
+- **On Request**: Full status report
+
+## Files to Update
+
+```
+./.cursor/tasks/[task-id]/
+├── README.md           # Task summary + status
+└── plan/
+    ├── plan.md         # Overall progress
+    └── phase-XX-*.md   # Phase details
+```

package/templates/.cursor/rules/project-profile.mdc

@@ -0,0 +1,54 @@
+---
+description: Sudoku Game project profile and conventions
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+# Sudoku Game Project Profile
+
+## Tech Stack
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| Language  | JavaScript (ESM on frontend, CJS on backend) | Node 18+ |
+| Backend   | Express 4 | REST, helmet + CORS + morgan, custom rate limiter |
+| Frontend  | React 18 + Vite 4 | styled-components, React Router |
+| Testing   | Jest (backend), Vitest + RTL (frontend) | Jest config in `backend/jest.config.js` |
+| Lint/Format | ESLint + Prettier | `.eslintrc.js` + `.prettierrc` in backend/frontend |
+
+## Commands (run from `sudoku-game/`)
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Run backend (3001) + frontend (5173) concurrently |
+| `npm run dev:backend` | Start Express API with nodemon |
+| `npm run dev:frontend` | Start Vite dev server |
+| `npm run test` | Jest backend, then Vitest frontend |
+| `npm run lint` | ESLint backend + frontend |
+| `npm run build` | Build frontend for production |
+
+## Backend Conventions
+- Base path: `/api/v1`. Routes live under `backend/src/routes/`; keep controllers thin and push logic into services.
+- Middleware order: helmet → CORS (pin `FRONTEND_URL` in production) → logging → body parsing → routes → 404 → error handler.
+- Error shape: JSON `{ error, code, message? }`; hide stack traces in production.
+- Rate limiting: required on public routes; stricter on `/hint`. Prefer shared store (e.g., Redis) if clustering later.
+- File size: keep source files under ~250 lines; extract helpers/services when growing.
+
+## Frontend Conventions
+- Functional components with hooks; favor context/hooks (`GameContext`, `useGameState`) for shared state.
+- Styling via styled-components; ensure accessible contrast and focus states.
+- Keep components presentational; isolate data fetching in services (`services/gameAPI.js`) and state in context/hooks.
+- Support keyboard navigation for board/controls; respect `prefers-reduced-motion`.
+
+## Testing Expectations
+- Backend: Jest + Supertest for controllers/services; cover error cases (invalid difficulty, rate limit, invalid board).
+- Frontend: Vitest + React Testing Library; cover board interactions, modals, API error surfaces.
+- Prefer Arrange-Act-Assert; one behavior per test; mock network in UI tests.
+
+## Security & Performance
+- Helmet must stay enabled; never log sensitive payloads.
+- Validate and sanitize all request inputs; reject bad difficulty/name/time/hints.
+- Target <250ms per API request locally; avoid heavy sync loops in validators.
+
+## Documentation
+- Update `docs/` when APIs or behaviors change (code standards, architecture, roadmap already initialized).
+

package/templates/.cursor/rules/python-pro/python-pro.mdc

@@ -0,0 +1,83 @@
+---
+description: Write idiomatic Python code with advanced features like decorators, generators, and async/await. Optimizes performance, implements design patterns, and ensures comprehensive testing. Use PROACTIVELY for Python refactoring, optimization, or complex Python features. Triggers on "async/await", "type hints", "pytest", "pydantic", "Python 3.10+", "TaskGroup", "dataclass", "protocol".
+globs:
+  - "**/*.py"
+  - "**/pyproject.toml"
+---
+
+# Python Pro
+
+Advanced Python development guidance for writing idiomatic, performant, and type-safe Python code (3.10+).
+
+## When to Use
+
+- Writing/refactoring Python code with modern patterns (3.10+)
+- Implementing async/await and structured concurrency
+- Adding type hints and runtime validation
+- Performance optimization and profiling
+- Testing with pytest and Hypothesis
+- Building CLI tools, APIs, or data pipelines
+
+## Core Principles
+
+1. **Type Safety**: Use modern type hints (`list[str]`, `X | Y`, not `typing` imports)
+2. **Async First**: Use `TaskGroup` for structured concurrency (Python 3.11+)
+3. **Validation**: Pydantic for APIs, dataclasses for simple data containers
+4. **Testing**: pytest with parametrization and property-based testing
+
+## Quick Reference
+
+### Modern Type Hints (Python 3.10+)
+
+```python
+def process(items: list[str], count: int | None = None) -> dict[str, int]:
+    return {item: len(item) for item in items[:count]}
+```
+
+### Structured Concurrency (Python 3.11+)
+
+```python
+async with asyncio.TaskGroup() as tg:
+    task1 = tg.create_task(fetch("url1"))
+    task2 = tg.create_task(fetch("url2"))
+```
+
+### Pydantic Validation
+
+```python
+from pydantic import BaseModel, Field
+class User(BaseModel):
+    name: str = Field(..., min_length=1)
+    age: int = Field(..., ge=0)
+```
+
+## Detailed References
+
+- [Type System](references/type-system.md) - Generics, Protocols, TypedDict, runtime checking
+- [Async Patterns](references/async-patterns.md) - TaskGroup, timeouts, generators
+- [Testing](references/testing.md) - pytest fixtures, parametrization, Hypothesis
+- [Performance](references/performance.md) - Profiling, memory optimization, Cython
+- [Error Handling](references/error-handling.md) - Exception design, logging, context managers
+- [Project Setup](references/project-setup.md) - pyproject.toml, UV, Ruff configuration
+- [Security](references/security.md) - Input validation, secrets, secure coding
+
+## Pattern Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `list[str]` | Modern type hints (3.9+) |
+| `X \| Y` | Union types (3.10+) |
+| `TaskGroup` | Structured concurrency (3.11+) |
+| `except* E` | Exception groups (3.11+) |
+| `Protocol` | Structural subtyping |
+| `@dataclass` | Simple data containers |
+| `@beartype` | Runtime type checking |
+| `BaseModel` | Validation + serialization |
+
+## Resources
+
+- Python Type Hints: https://docs.python.org/3/library/typing.html
+- Pydantic: https://docs.pydantic.dev/
+- pytest: https://docs.pytest.org/
+- UV Package Manager: https://github.com/astral-sh/uv
+- Ruff Linter: https://github.com/astral-sh/ruff

package/templates/.cursor/rules/python-pro/references/async-patterns.md

@@ -0,0 +1,96 @@
+# Async Patterns
+
+Modern async/await patterns for Python 3.11+.
+
+## TaskGroup (Structured Concurrency)
+
+```python
+import asyncio
+from asyncio import TaskGroup
+
+async def fetch_all(urls: list[str]) -> list[str]:
+    results: list[str] = []
+    async with TaskGroup() as tg:
+        tasks = [tg.create_task(fetch(url)) for url in urls]
+    return [t.result() for t in tasks]
+```
+
+**Benefits:**
+- Automatic cleanup on exit
+- If one task fails, others are cancelled
+- No orphaned tasks
+
+## Timeouts (Python 3.11+)
+
+```python
+async def fetch_with_timeout(url: str) -> str:
+    try:
+        async with asyncio.timeout(5.0):
+            return await fetch(url)
+    except TimeoutError:
+        return f"Timeout: {url}"
+```
+
+## Async Context Managers
+
+```python
+class AsyncDB:
+    async def __aenter__(self):
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.disconnect()
+
+async def main():
+    async with AsyncDB() as db:
+        await db.query("SELECT 1")
+```
+
+## Async Generators
+
+```python
+from typing import AsyncIterator
+
+async def stream_data(n: int) -> AsyncIterator[int]:
+    for i in range(n):
+        await asyncio.sleep(0.1)
+        yield i
+
+async def consume():
+    async for item in stream_data(10):
+        print(item)
+```
+
+## Exception Groups (Python 3.11+)
+
+```python
+try:
+    async with TaskGroup() as tg:
+        tg.create_task(task1())
+        tg.create_task(task2())
+except* ValueError as eg:
+    for exc in eg.exceptions:
+        print(f"Validation: {exc}")
+except* ConnectionError as eg:
+    for exc in eg.exceptions:
+        print(f"Connection: {exc}")
+```
+
+## Performance: uvloop
+
+```python
+import asyncio
+import uvloop
+
+asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+asyncio.run(main())  # Much faster event loop
+```
+
+## Anti-Patterns
+
+**Avoid**: `asyncio.gather()` with `return_exceptions=True` (hides errors)
+**Prefer**: `TaskGroup` for proper error handling
+
+**Avoid**: Blocking calls in async code
+**Prefer**: `asyncio.to_thread()` for blocking I/O

package/templates/.cursor/rules/python-pro/references/error-handling.md

@@ -0,0 +1,84 @@
+# Error Handling
+
+Exception design, logging, and context managers.
+
+## Custom Exception Hierarchy
+
+```python
+class ApplicationError(Exception):
+    """Base exception for application."""
+
+class ValidationError(ApplicationError):
+    """Data validation failed."""
+
+class DatabaseError(ApplicationError):
+    """Database operation failed."""
+```
+
+## Best Practices
+
+```python
+# Bad: too broad
+try:
+    risky_operation()
+except Exception:
+    pass
+
+# Good: specific exceptions
+try:
+    result = divide(a, b)
+except ZeroDivisionError:
+    print("Cannot divide by zero")
+except TypeError as e:
+    print(f"Invalid type: {e}")
+
+# Good: focused try blocks
+try:
+    validated = validate(data)
+except ValidationError as e:
+    return handle_validation_error(e)
+```
+
+## Context Managers
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def managed_resource():
+    resource = acquire()
+    try:
+        yield resource
+    finally:
+        release(resource)
+
+with managed_resource() as r:
+    use(r)  # Cleanup guaranteed
+```
+
+## Logging
+
+```python
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# In exception handlers - includes stack trace
+try:
+    risky()
+except Exception:
+    logger.exception("Error occurred")
+```
+
+**Structured logging** (structlog):
+```python
+import structlog
+logger = structlog.get_logger()
+logger.info("user_login", user_id=123, ip="192.168.1.1")
+```
+
+See also: [Security](security.md) - input validation, secrets, secure random

package/templates/.cursor/rules/python-pro/references/performance.md

@@ -0,0 +1,71 @@
+# Performance
+
+Profiling, optimization, and memory management.
+
+## Profiling
+
+```python
+# cProfile - function-level
+import cProfile, pstats
+profiler = cProfile.Profile()
+profiler.enable()
+expensive_function()
+profiler.disable()
+pstats.Stats(profiler).sort_stats('cumulative').print_stats(10)
+
+# line_profiler - line-by-line
+# uv add --dev line-profiler
+@profile
+def slow_function():
+    return [i ** 2 for i in range(10000)]
+# Run: kernprof -l -v script.py
+
+# memory_profiler
+from memory_profiler import profile
+@profile
+def memory_intensive():
+    return [i for i in range(1000000)]
+```
+
+## Memory Optimization
+
+```python
+# __slots__ - reduce memory per instance
+class Optimized:
+    __slots__ = ['x', 'y']
+    def __init__(self, x, y):
+        self.x, self.y = x, y
+
+# Generators vs lists - process one at a time
+sum(i ** 2 for i in range(1000000))  # Memory efficient
+```
+
+## Concurrent vs Parallel
+
+```python
+import concurrent.futures
+
+# CPU-bound: ProcessPoolExecutor
+with concurrent.futures.ProcessPoolExecutor() as ex:
+    results = ex.map(cpu_work, data)
+
+# I/O-bound: ThreadPoolExecutor or asyncio
+with concurrent.futures.ThreadPoolExecutor() as ex:
+    results = ex.map(blocking_io, urls)
+```
+
+## Quick Wins
+
+1. `dict`/`set` for O(1) lookups
+2. `collections.deque` for queue operations
+3. `str.join()` over `+=` for string concatenation
+4. `functools.lru_cache` for memoization
+5. `itertools` for efficient iteration
+
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=128)
+def expensive(n: int) -> int:
+    return sum(i ** 2 for i in range(n))
+```

package/templates/.cursor/rules/python-pro/references/project-setup.md

@@ -0,0 +1,78 @@
+# Project Setup
+
+Modern Python project configuration with UV, Ruff, and pyproject.toml.
+
+## Project Structure (src layout)
+
+```
+my_project/
+├── src/my_package/
+│   ├── __init__.py
+│   └── main.py
+├── tests/test_main.py
+├── pyproject.toml
+└── README.md
+```
+
+## pyproject.toml
+
+```toml
+[project]
+name = "my-package"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.27.0", "pydantic>=2.0.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "ruff>=0.8.0", "mypy>=1.11.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "C4"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+```
+
+## UV Commands
+
+```bash
+# Install
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Project setup
+uv init my-project && cd my-project
+uv add httpx pydantic
+uv add --dev pytest ruff mypy
+uv sync
+
+# Run
+uv run python main.py
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+uv run mypy src/
+```
+
+## VS Code Settings
+
+```json
+{
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true
+  },
+  "python.analysis.typeCheckingMode": "basic"
+}
+```