agent-skill-kit 3.9.135

package/.agent/skills/python-pro/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: python-pro
+description: >-
+  Python development with FastAPI, Django, or Flask. Async patterns, type hints, project structure.
+  Use when building Python backends, scripts, or choosing Python frameworks.
+  NOT for Node.js projects (use nodejs-pro) or general AI agents (use google-adk-python).
+category: backend-specialist
+triggers: ["Python", "pip", "FastAPI", "Django", "Flask"]
+coordinates_with: ["api-architect", "test-architect", "data-modeler", "problem-checker", "knowledge-compiler"]
+success_metrics: ["Correct Framework Selection", "Type Hint Coverage"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Python Pro — Framework Selection & Architecture
+
+> Decision-making principles. Not patterns to copy. Ask, classify, decide.
+
+---
+
+## 5 Must-Ask Questions (Before Decision)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Target Scope? | Single Script / API / Full-Stack / Workers |
+| 2 | Project Scale? | MVP / Production / FAANG Scale |
+| 3 | Current Framework? | Green field vs Legacy modification? |
+| 4 | Async Requirements? | High I/O throughput vs CPU heavy? |
+| 5 | DB Dependencies? | Relational vs NoSQL, Async DB drivers? |
+
+---
+
+## When to Use
+
+| Situation | Approach |
+|-----------|----------|
+| Choosing Python framework | Use decision tree |
+| API-first / microservices | Consider FastAPI |
+| Full-stack web / CMS | Consider Django |
+| Async vs sync decision | Check I/O vs CPU classification |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Framework selection (5 branches) | API design (→ api-architect) |
+| Async/sync classification | Testing strategy (→ test-architect) |
+| Type hint rules | Database schema (→ data-modeler) |
+| Architecture layering | Code implementation |
+
+**Expert decision skill:** Produces recommendations. Does not write code.
+
+---
+
+## Framework Decision Tree (Deterministic)
+
+```
+What are you building?
+│
+├── API-first / Microservices  → FastAPI
+├── Full-stack web / CMS       → Django
+├── Simple / Script / Learning → Flask
+├── AI/ML API serving          → FastAPI
+└── Background workers         → Celery + any
+```
+
+**If user has explicit preference → respect it.** Ask when unclear.
+
+---
+
+## Async vs Sync (Deterministic)
+
+| Workload | Decision | Rationale |
+|----------|----------|-----------|
+| I/O-bound (HTTP, DB, file) | `async` | Waiting for external |
+| CPU-bound (compute) | `sync` + multiprocessing | Number crunching |
+| Mixed | Async with sync offload | `run_in_executor` |
+
+**Constraints:** Never use sync libraries in async code. Never force async for CPU work.
+
+---
+
+## Architecture Layering (Fixed)
+
+```
+Routes (HTTP handlers)
+  └→ Services (business logic)
+      └→ Repositories (data access)
+```
+
+**Rule:** No business logic in routes/views. Routes delegate to services.
+
+---
+
+## Type Hints & Validation (Mandatory)
+
+| Rule | Scope |
+|------|-------|
+| Type hints on all public APIs | Functions, methods, return types |
+| Pydantic for validation | All input/output boundaries |
+| No `Any` in public signatures | Use specific types or generics |
+
+---
+
+## Decision Checklist
+
+- [ ] Asked user about framework preference?
+- [ ] Chosen framework for THIS context?
+- [ ] Decided async vs sync?
+- [ ] Planned type hint strategy?
+- [ ] Defined project structure?
+- [ ] Considered background tasks (Celery)?
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_UNKNOWN_PROJECT_TYPE` | Yes | Project type not one of 5 |
+| `ERR_UNKNOWN_FRAMEWORK` | Yes | Framework not fastapi/django/flask |
+
+**Zero internal retries.** Same context = same recommendation.
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `decision_started` | `{"project_type": "...", "scale": "..."}` | `INFO` |
+| `framework_selected` | `{"framework": "fastapi", "rationale": "..."}` | `INFO` |
+| `async_sync_classified` | `{"mode": "async", "mix_workload": false}` | `WARN` |
+| `arch_recommendation_provided` | `{"layer_complexity": "high"}` | `INFO` |
+
+All architectural decision outputs MUST emit a `decision_started` and `arch_recommendation_provided` event.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Default to Django for simple APIs | Choose framework per context |
+| Use sync libraries in async code | Use async-compatible libraries |
+| Skip type hints on public APIs | Annotate all public functions |
+| Put business logic in routes/views | Separate: routes → services → repos |
+| Always pick the same framework | Ask user, evaluate context |
+
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [framework-selection.md](rules/framework-selection.md) | Framework comparison | Choosing framework |
+| [async-patterns.md](rules/async-patterns.md) | Async/sync patterns | Concurrency decisions |
+| [type-hints.md](rules/type-hints.md) | Type annotation rules | Type strategy |
+| [project-structure.md](rules/project-structure.md) | Directory layouts | New project |
+| [fastapi-patterns.md](rules/fastapi-patterns.md) | FastAPI specifics | FastAPI project |
+| [django-patterns.md](rules/django-patterns.md) | Django specifics | Django project |
+| [testing-patterns.md](rules/testing-patterns.md) | Python testing | Writing tests |
+| [engineering-spec.md](rules/engineering-spec.md) | Full spec | Architecture review |
+
+**Selective reading:** Load ONLY the reference file matching your current decision.
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `api-architect` | Skill | API design |
+| `test-architect` | Skill | Testing |
+| `data-modeler` | Skill | Database |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/python-pro/rules/_sections.md

@@ -0,0 +1,50 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
+
+## 2. Django (django)
+
+**Impact:** LOW  
+**Description:** Django patterns and best practices.
+
+## 3. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 4. Fastapi (fastapi)
+
+**Impact:** LOW  
+**Description:** Fastapi patterns and best practices.
+
+## 5. Framework (framework)
+
+**Impact:** LOW  
+**Description:** Framework patterns and best practices.
+
+## 6. Project (project)
+
+**Impact:** LOW  
+**Description:** Project patterns and best practices.
+
+## 7. Testing (testing)
+
+**Impact:** LOW  
+**Description:** Testing patterns and best practices.
+
+## 8. Type (type)
+
+**Impact:** LOW  
+**Description:** Type patterns and best practices.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/python-pro/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/python-pro/rules/async-patterns.md

@@ -0,0 +1,168 @@
+---
+name: async-patterns
+description: Python async patterns — asyncio, gather, TaskGroup, run_in_executor, and async library selection
+title: "Python Async Patterns"
+impact: CRITICAL
+impactDescription: "Significant performance or security impact"
+tags: async, patterns
+---
+
+# Python Async Patterns
+
+> I/O-bound → async. CPU-bound → sync + multiprocessing. Never mix carelessly.
+
+---
+
+## When to Use
+
+| Workload | Decision | Example |
+|----------|----------|---------|
+| I/O-bound | `async def` | DB queries, HTTP calls, file I/O |
+| CPU-bound | `def` + multiprocessing | ML inference, image processing |
+| Mixed | Async + `run_in_executor` | Web scraping + parsing |
+
+---
+
+## Core Patterns
+
+### Basic Async Function
+
+```python
+import asyncio
+import httpx
+
+async def fetch_user(user_id: int) -> dict:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"https://api.example.com/users/{user_id}")
+        response.raise_for_status()
+        return response.json()
+```
+
+### Concurrent Execution (asyncio.gather)
+
+```python
+async def fetch_all_users(user_ids: list[int]) -> list[dict]:
+    """Fetch multiple users concurrently — much faster than sequential."""
+    async with httpx.AsyncClient() as client:
+        tasks = [
+            client.get(f"https://api.example.com/users/{uid}")
+            for uid in user_ids
+        ]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+    results = []
+    for resp in responses:
+        if isinstance(resp, Exception):
+            continue  # Skip failed requests
+        results.append(resp.json())
+    return results
+```
+
+### TaskGroup (Python 3.11+, preferred)
+
+```python
+async def fetch_all_users_v2(user_ids: list[int]) -> list[dict]:
+    """TaskGroup: structured concurrency with automatic cancellation on failure."""
+    results: list[dict] = []
+
+    async with asyncio.TaskGroup() as tg:
+        async def fetch_one(uid: int):
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(f"https://api.example.com/users/{uid}")
+                results.append(resp.json())
+
+        for uid in user_ids:
+            tg.create_task(fetch_one(uid))
+
+    return results
+```
+
+### CPU-Bound Offload (run_in_executor)
+
+```python
+import asyncio
+from concurrent.futures import ProcessPoolExecutor
+
+# CPU-heavy work runs in separate process
+def compute_hash(data: bytes) -> str:
+    import hashlib
+    return hashlib.sha256(data).hexdigest()
+
+async def process_file(file_path: str) -> str:
+    """Offload CPU work to avoid blocking the event loop."""
+    loop = asyncio.get_event_loop()
+    data = await asyncio.to_thread(open(file_path, 'rb').read)
+
+    with ProcessPoolExecutor() as pool:
+        result = await loop.run_in_executor(pool, compute_hash, data)
+    return result
+```
+
+---
+
+## Async Library Selection
+
+| Need | Sync Library | Async Library |
+|------|-------------|---------------|
+| HTTP client | requests | **httpx** |
+| PostgreSQL | psycopg2 | **asyncpg** / psycopg3 async |
+| MySQL | mysql-connector | **aiomysql** |
+| Redis | redis-py (sync) | **redis-py** (async mode) / aioredis |
+| File I/O | open() | **aiofiles** |
+| ORM | SQLAlchemy sync | **SQLAlchemy 2.0** async / **Tortoise** |
+| MongoDB | pymongo | **motor** |
+| WebSockets | — | **websockets** |
+
+---
+
+## FastAPI: async def vs def
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+# ✅ Use async def — for I/O-bound with async drivers
+@app.get("/users/{user_id}")
+async def get_user(user_id: int):
+    user = await db.fetch_one("SELECT * FROM users WHERE id = $1", user_id)
+    return user
+
+# ✅ Use def — for sync operations (FastAPI runs in threadpool automatically)
+@app.get("/report")
+def generate_report():
+    # This blocks, but FastAPI handles it in a thread
+    return create_pdf_report()
+
+# ❌ Don't — use sync DB driver in async def (blocks event loop!)
+@app.get("/bad")
+async def bad_example():
+    user = db.execute("SELECT ...")  # BLOCKS the entire event loop!
+    return user
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Use `requests` in async code | Use `httpx` (async) |
+| `await` CPU-bound functions | Use `run_in_executor` |
+| Sync DB driver in `async def` | Use async driver or `def` |
+| `time.sleep()` in async | `await asyncio.sleep()` |
+| Create event loop inside async | Use `asyncio.get_event_loop()` |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [fastapi-patterns.md](fastapi-patterns.md) | FastAPI async specifics |
+| [framework-selection.md](framework-selection.md) | Framework decision |
+| [testing-patterns.md](testing-patterns.md) | Testing async code |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/python-pro/rules/django-patterns.md

@@ -0,0 +1,194 @@
+---
+name: django-patterns
+description: Django patterns — models, views, DRF serializers, async views, query optimization, signals, and migrations
+title: "Django Patterns (2025)"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: django, patterns
+---
+
+# Django Patterns (2025)
+
+> Fat models, thin views. Use managers for queries. DRF for APIs.
+
+---
+
+## Model Design
+
+```python
+from django.db import models
+from django.utils import timezone
+
+class UserManager(models.Manager):
+    """Custom manager — encapsulate common queries."""
+    def active(self):
+        return self.filter(is_active=True)
+
+    def recently_joined(self, days: int = 7):
+        cutoff = timezone.now() - timezone.timedelta(days=days)
+        return self.filter(created_at__gte=cutoff, is_active=True)
+
+class User(models.Model):
+    email = models.EmailField(unique=True)
+    name = models.CharField(max_length=100)
+    is_active = models.BooleanField(default=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    objects = UserManager()
+
+    class Meta:
+        ordering = ["-created_at"]
+        indexes = [models.Index(fields=["email"])]
+
+    def __str__(self) -> str:
+        return self.name
+
+    @property
+    def display_name(self) -> str:
+        """Business logic belongs in model, not views."""
+        return self.name or self.email.split("@")[0]
+```
+
+---
+
+## DRF Serializers
+
+```python
+from rest_framework import serializers
+
+class UserSerializer(serializers.ModelSerializer):
+    display_name = serializers.CharField(read_only=True)
+
+    class Meta:
+        model = User
+        fields = ["id", "email", "name", "display_name", "created_at"]
+        read_only_fields = ["id", "created_at"]
+
+class UserCreateSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ["email", "name", "password"]
+        extra_kwargs = {"password": {"write_only": True}}
+
+    def create(self, validated_data):
+        return User.objects.create_user(**validated_data)
+```
+
+---
+
+## Views / ViewSets
+
+```python
+from rest_framework import viewsets, status
+from rest_framework.decorators import action
+from rest_framework.response import Response
+
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.active()
+    serializer_class = UserSerializer
+
+    def get_serializer_class(self):
+        if self.action == "create":
+            return UserCreateSerializer
+        return UserSerializer
+
+    @action(detail=False, methods=["get"])
+    def recent(self, request):
+        """Custom action: GET /users/recent/"""
+        users = User.objects.recently_joined()
+        serializer = self.get_serializer(users, many=True)
+        return Response(serializer.data)
+```
+
+---
+
+## Django Async Views (5.0+)
+
+```python
+# Async function-based view
+from django.http import JsonResponse
+import httpx
+
+async def external_api_view(request):
+    """Use async for I/O-bound views."""
+    async with httpx.AsyncClient() as client:
+        response = await client.get("https://api.example.com/data")
+    return JsonResponse(response.json())
+
+# ASGI deployment required:
+# uvicorn myproject.asgi:application --workers 4
+```
+
+---
+
+## Query Optimization
+
+```python
+# ❌ N+1 Problem
+users = User.objects.all()
+for user in users:
+    print(user.profile.bio)      # Each access = 1 query!
+    print(user.posts.count())    # Each access = 1 query!
+
+# ✅ Fix: select_related (ForeignKey / OneToOne)
+users = User.objects.select_related("profile").all()
+
+# ✅ Fix: prefetch_related (ManyToMany / Reverse FK)
+users = User.objects.prefetch_related("posts").all()
+
+# ✅ Select specific fields
+users = User.objects.only("id", "email", "name").all()
+
+# ✅ Annotate counts without extra queries
+from django.db.models import Count
+users = User.objects.annotate(post_count=Count("posts")).all()
+```
+
+---
+
+## Signals (Use Sparingly)
+
+```python
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+
+@receiver(post_save, sender=User)
+def create_user_profile(sender, instance, created, **kwargs):
+    """Auto-create profile when user is created."""
+    if created:
+        Profile.objects.create(user=instance)
+
+# Register in apps.py:
+# class UsersConfig(AppConfig):
+#     def ready(self):
+#         import users.signals
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Business logic in views | Fat models, thin views |
+| Raw SQL everywhere | Use ORM + managers |
+| Forget `select_related` | Profile queries, fix N+1 |
+| Overuse signals | Prefer explicit service calls |
+| `settings.py` monolith | Split: base/dev/prod |
+| Skip migrations | Always `makemigrations` + `migrate` |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [framework-selection.md](framework-selection.md) | Why Django |
+| [project-structure.md](project-structure.md) | Django directory layout |
+| [testing-patterns.md](testing-patterns.md) | Testing Django |
+| [async-patterns.md](async-patterns.md) | Async in Django |
+
+---
+
+⚡ PikaKit v3.9.134