exonous 0.0.0-stage → 2.10.4

package/assets/techne/skills/ml/reference/prompt-optimizer.md

@@ -0,0 +1,107 @@
+# Prompt optimizer (advisory)
+
+Analyze a draft user prompt and return a **better prompt to paste** — plus diagnosis. **Do not execute** the underlying task, write production code, or mutate the repo unless the user starts a normal task request.
+
+## Triggers
+
+- “Optimize / improve / rewrite my prompt”
+- User pastes a vague instruction and asks how to ask the agent better
+- **Not** for “optimize this code/performance” — that is implementation work
+- **Not** when user says “just do it” — tell them to send a standard task message instead
+
+## Pipeline
+
+### 0 — Context
+
+- Read project `CLAUDE.md` when present
+- Infer stack from manifests (`package.json`, `pyproject.toml`, `go.mod`, etc.)
+- If greenfield, mark stack unknown in output
+
+### 1 — Intent
+
+| Intent | Signals |
+|--------|---------|
+| Feature | build, add, implement |
+| Bug | fix, broken, error |
+| Refactor | restructure, clean up |
+| Research | how, explore, investigate |
+| Test | coverage, verify |
+| Review | audit, PR review |
+| Docs | document, README |
+| Infra | deploy, CI, database |
+| Design | architecture, data model |
+
+### 2 — Scope
+
+| Scope | Heuristic | Orchestration |
+|-------|-----------|---------------|
+| Trivial | one file | direct task |
+| Low | one module | single skill |
+| Medium | multi-file, one domain | skill chain + **techne:quality** verify |
+| High | cross-domain | plan first (**techne:research** / **exo-pm**) |
+| Epic | multi-session | phased plan, **/session-handoff** between sessions |
+
+### 3 — Kit mapping (techne names)
+
+| Intent | Skills / agents |
+|--------|-----------------|
+| Feature | **techne:quality**, stack skill (**techne:web**, **techne:react**, **techne:python**, …), **exo-qa** review |
+| Bug | **techne:quality**, stack skill |
+| Refactor | **techne:quality**, **code-review** |
+| Research | **techne:research**, **atlas**, **biblos** |
+| Test | **techne:quality** |
+| Review | **code-review**, **security-review**, **exo-qa**, **exo-security** |
+| Infra | **techne:delivery**, **exo-infra**, **exo-devops** |
+| ML / LLM | **techne:ml**, **exo-data-ai** |
+
+Add stack skill from detection table (e.g. Python → **techne:python**, Postgres → **techne:databases**).
+
+### 4 — Missing context scan
+
+Flag gaps: acceptance criteria, scope boundaries, error handling, security, tests, performance, a11y (**ui-design** `audit`/`harden` for UI), migrations. If **3+** critical gaps, ask up to **3** clarifying questions before emitting the optimized prompt.
+
+### 5 — Model recommendation (house rule)
+
+| Scope | Agent model tier |
+|-------|-------------------|
+| Trivial–medium planning, research, prompt writing | Economical |
+| Production code implementation | Robust |
+| Epic architecture | Robust for plan; economical for doc-only phases unless deep reasoning required |
+
+Split HIGH/EPIC work into sequential prompts (research → plan → implement phases → integration review).
+
+## Output format (match user language)
+
+### 1. Diagnosis
+
+Strengths; issues table (problem / impact / fix); clarification list (or auto-detected facts).
+
+### 2. Recommended kit
+
+| Type | Name | Purpose |
+
+### 3. Optimized prompt — full
+
+Single fenced block, self-contained: context, stack, acceptance criteria, verification, explicit “do not” scope, skill/agent hints.
+
+### 4. Optimized prompt — quick
+
+One-liner patterns per intent (e.g. feature: plan → TDD → code-review → verify).
+
+### 5. Rationale table
+
+| Enhancement | Why |
+
+Footer: user may request edits or switch to a normal execution request.
+
+## Example (English, abbreviated)
+
+**In:** “Add profile PATCH API with validation”
+
+**Out (full prompt sketch):** stack-detected Go + chi; PATCH `/api/users/:id`; authz self-only; table-driven tests; follow existing handlers; **techne:services** + **techne:go**; acceptance = 200/400/401 paths; do not change schema; run tests + build before review.
+
+## Related
+
+- **techne:research** — discovery before large prompts
+- **techne:ml** `cost-aware-llm-pipeline` — token spend when prompts embed huge context
+- **/session-handoff** — multi-session epic work

package/assets/techne/skills/ml/reference/pytorch-patterns.md

@@ -0,0 +1,164 @@
+# PyTorch patterns
+
+Idiomatic training and inference: portable devices, reproducible seeds, explicit modes, and memory-aware loops. Confirm API details via **biblos** for your installed PyTorch major version.
+
+## Principles
+
+**Device-agnostic**
+
+```python
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+net = Model().to(device)
+batch_x = batch_x.to(device)
+```
+
+**Reproducibility** (document GPU nondeterminism)
+
+```python
+def seed_all(seed: int) -> None:
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+    import numpy as np, random
+    np.random.seed(seed)
+    random.seed(seed)
+    torch.backends.cudnn.deterministic = True
+    torch.backends.cudnn.benchmark = False
+```
+
+**Shapes** — comment tensor ranks in `forward`; verify after refactors.
+
+## Module layout
+
+Split feature blocks and heads; initialize weights explicitly; never allocate parameters inside `forward`.
+
+```python
+class ConvNet(nn.Module):
+    def __init__(self, n_classes: int, drop: float = 0.5) -> None:
+        super().__init__()
+        self.backbone = nn.Sequential(
+            nn.Conv2d(3, 64, 3, padding=1),
+            nn.BatchNorm2d(64),
+            nn.ReLU(inplace=False),
+            nn.MaxPool2d(2),
+        )
+        self.head = nn.Sequential(nn.Dropout(drop), nn.Linear(64 * 16 * 16, n_classes))
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = self.backbone(x)
+        return self.head(x.flatten(1))
+```
+
+## Training loop
+
+```python
+def train_epoch(
+    net: nn.Module,
+    loader: DataLoader,
+    opt: torch.optim.Optimizer,
+    loss_fn: nn.Module,
+    device: torch.device,
+    scaler: torch.amp.GradScaler | None = None,
+) -> float:
+    net.train()
+    running = 0.0
+    for x, y in loader:
+        x, y = x.to(device), y.to(device)
+        opt.zero_grad(set_to_none=True)
+        with torch.amp.autocast("cuda", enabled=scaler is not None):
+            logits = net(x)
+            loss = loss_fn(logits, y)
+        if scaler:
+            scaler.scale(loss).backward()
+            scaler.unscale_(opt)
+            nn.utils.clip_grad_norm_(net.parameters(), 1.0)
+            scaler.step(opt)
+            scaler.update()
+        else:
+            loss.backward()
+            nn.utils.clip_grad_norm_(net.parameters(), 1.0)
+            opt.step()
+        running += loss.item()
+    return running / len(loader)
+```
+
+## Evaluation
+
+```python
+@torch.no_grad()
+def eval_epoch(net, loader, loss_fn, device) -> tuple[float, float]:
+    net.eval()
+    total_loss, correct, n = 0.0, 0, 0
+    for x, y in loader:
+        x, y = x.to(device), y.to(device)
+        logits = net(x)
+        total_loss += loss_fn(logits, y).item()
+        correct += (logits.argmax(1) == y).sum().item()
+        n += y.size(0)
+    return total_loss / len(loader), correct / n
+```
+
+## Data loading
+
+```python
+loader = DataLoader(
+    ds,
+    batch_size=32,
+    shuffle=True,
+    num_workers=4,
+    pin_memory=True,
+    persistent_workers=True,
+    drop_last=True,
+)
+```
+
+Variable-length batches: pad in `collate_fn` with `nn.utils.rnn.pad_sequence`.
+
+## Checkpoints
+
+Save full training state when resuming; load on CPU with safe weights:
+
+```python
+def persist(path: str, net, opt, epoch: int, loss: float) -> None:
+    torch.save(
+        {"epoch": epoch, "net": net.state_dict(), "opt": opt.state_dict(), "loss": loss},
+        path,
+    )
+
+def restore(path: str, net, opt=None) -> dict:
+    blob = torch.load(path, map_location="cpu", weights_only=True)
+    net.load_state_dict(blob["net"])
+    if opt and "opt" in blob:
+        opt.load_state_dict(blob["opt"])
+    return blob
+```
+
+Prefer `state_dict` over pickling whole modules.
+
+## Performance knobs
+
+| Technique | When |
+|-----------|------|
+| `torch.amp.autocast` + `GradScaler` | GPU training throughput |
+| `torch.utils.checkpoint.checkpoint` | OOM on large models |
+| `torch.compile(net, mode="reduce-overhead")` | PyTorch 2+ stable graphs |
+| `pin_memory=True` | Host→device copies |
+
+Profile with `torch.profiler`; inspect VRAM via `torch.cuda.memory_summary()`.
+
+## Idiom quick reference
+
+| Practice | Reason |
+|----------|--------|
+| `net.train()` / `net.eval()` | Dropout & BatchNorm behavior |
+| `torch.no_grad()` | Inference / metrics |
+| `zero_grad(set_to_none=True)` | Less alloc on large models |
+| Avoid inplace ops on tensors needing grad | Broken autograd |
+| `.item()` only for logging after `backward` | Keeps graph intact |
+| Move model once before epoch loop | Avoid per-step `.cuda()` |
+
+## Anti-patterns
+
+- Validation while `train()` mode active
+- `torch.save(net, path)` portability trap
+- Hardcoded `.cuda()` without fallback
+- Creating weights inside `forward` each call

package/assets/techne/skills/php/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: php
+description: Laravel HTTP layer, Eloquent, form requests, API resources, queues, and caching for production APIs. Use when building or reviewing Laravel apps, routes, or Eloquent models.
+---
+
+# techne:php
+
+Laravel-specific patterns. Generic HTTP/API design: **techne:services**; migrations and SQL tuning: **techne:databases**; CI/deploy: **techne:delivery**.
+
+## Non-negotiables
+
+1. Thin controllers: validate in **FormRequest**, orchestrate in **Actions** or **Services**, persist via repositories or Eloquent as appropriate.
+2. Authorize in `authorize()` on form requests or policies—route-model binding alone is not access control.
+3. Nested routes: enable `scopeBindings()` (or equivalent) so child models cannot be accessed across parent tenants.
+4. Eloquent lists: eager-load relationships (`with([...])`) before loops; paginate with explicit `latest()` / indexed order columns.
+5. Multi-step writes: `DB::transaction()`; keep side effects (mail, webhooks) in queued jobs with idempotent handlers.
+6. API shape: **JsonResource** + consistent envelope (`data`, `meta`, errors); never leak stack traces in production JSON.
+7. Casts: enums/value objects on models; avoid stringly-typed status fields in business logic.
+8. Config in `config/*.php`, secrets in `.env`; run `config:cache` in production after deploy.
+9. Migrations: anonymous classes, reversible `down()`, foreign keys with explicit `constrained()` behavior.
+10. **biblos** MCP for Laravel APIs; security regressions: **security-review** / **exo-security**.
+
+## References
+
+| File | Load when |
+|------|-----------|
+| [reference/laravel.md](reference/laravel.md) | Structure, routing, Eloquent, resources, jobs, cache |

package/assets/techne/skills/php/reference/laravel.md

@@ -0,0 +1,142 @@
+# Laravel patterns
+
+## Layers
+
+```
+app/Actions/          # single use-case classes
+app/Services/         # coordination across models/gateways
+app/Http/Requests/    # validation + authorize()
+app/Http/Resources/   # JSON transformers
+app/Models/
+app/Jobs/
+routes/api.php
+```
+
+Flow: **Route → Controller → FormRequest → Action/Service → Model/Repository → Resource response**.
+
+## Routing
+
+```php
+Route::middleware('auth:sanctum')->group(function (): void {
+    Route::apiResource('orders', OrderController::class);
+});
+
+Route::scopeBindings()->prefix('accounts/{account}')->group(function (): void {
+    Route::get('projects/{project}', [ProjectController::class, 'show']);
+});
+```
+
+- Parameter names match model keys (`{conversation}` → `Conversation`).
+- `Route::model()` or `resolveRouteBinding()` when parameter names differ from class names.
+
+## Controller + action
+
+```php
+final class OrderController extends Controller
+{
+    public function __construct(private PlaceOrderAction $placeOrder) {}
+
+    public function store(StoreOrderRequest $request): JsonResponse
+    {
+        $order = $this->placeOrder->handle($request->toDto());
+
+        return response()->json([
+            'data' => OrderResource::make($order),
+            'meta' => null,
+        ], 201);
+    }
+}
+```
+
+## Form requests
+
+```php
+final class StoreOrderRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()?->can('create', Order::class) ?? false;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'customer_id' => ['required', 'integer', 'exists:customers,id'],
+            'items' => ['required', 'array', 'min:1'],
+            'items.*.sku' => ['required', 'string'],
+            'items.*.qty' => ['required', 'integer', 'min:1'],
+        ];
+    }
+}
+```
+
+## Eloquent
+
+```php
+final class Project extends Model
+{
+    use SoftDeletes;
+
+    protected $fillable = ['name', 'owner_id', 'status'];
+
+    protected $casts = ['status' => ProjectStatus::class];
+
+    public function owner(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function scopeActive(Builder $query): Builder
+    {
+        return $query->whereNull('archived_at');
+    }
+}
+```
+
+- Prefer one mechanism for default filters (global scope **or** named scope, not redundant both).
+- Custom `Attribute` casts for money/value objects.
+
+## Queries
+
+```php
+Order::query()
+    ->with(['customer', 'items.product'])
+    ->latest('id')
+    ->paginate(25);
+```
+
+Extract complex filters into query objects returning cloned builders.
+
+## Transactions and events
+
+```php
+DB::transaction(function () use ($order): void {
+    $order->markPaid();
+    $order->items()->update(['paid_at' => now()]);
+});
+
+event(new OrderPaid($order));
+```
+
+Dispatch slow listeners as queued jobs (`ShouldQueue`); make handlers idempotent (unique job keys).
+
+## API resources
+
+Wrap collections; include pagination meta (`currentPage`, `perPage`, `total`).
+
+## Caching
+
+- Remember/cache expensive aggregates with TTL; tag caches when driver supports tags.
+- Flush related keys on `created/updated/deleted` model events.
+
+## Migrations
+
+Anonymous migration classes; plural `snake_case` tables; foreign IDs `constrained()` with explicit `cascadeOnDelete()` where intended.
+
+## Container bindings
+
+Register interfaces → implementations in `AppServiceProvider::register()`.
+
+## Testing pointers
+
+Use **techne:quality** for PHPUnit/Pest strategy; feature tests hit HTTP kernel with `RefreshDatabase` or transactions per project convention.

package/assets/techne/skills/python/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: python
+description: Python idioms, pytest, Django/DRF, and FastAPI patterns for typed, testable backends. Use when writing or reviewing Python services, ORM/API layers, or pytest suites.
+---
+
+# techne:python
+
+Covers general Python style, pytest strategy, Django (including DRF), and FastAPI. For cross-stack API design, errors, and hexagonal boundaries see **techne:services**; databases and migrations see **techne:databases**; TDD and browser QA see **techne:quality**.
+
+## Non-negotiables
+
+1. Type-annotate public functions and data crossing module boundaries; enforce with mypy (or pyright) in CI.
+2. Ship `src/` layout + `pyproject.toml`; pin Python with `requires-python`; run **ruff** (lint + import sort) and **black** (or ruff format) before merge.
+3. Catch specific exceptions only; wrap domain failures in a small hierarchy; always chain with `raise ... from exc`.
+4. Release files, sockets, and DB sessions via `with` / async context managers; roll back failed transactions explicitly.
+5. No mutable defaults (`def f(x, items=None)`); compare singletons with `is`; prefer `isinstance` over `type() ==`.
+6. Unit tests: mock outbound HTTP, email, and payment clients; keep tests independent; name tests by behavior.
+7. Aim ≥80% line coverage; auth, billing, and permission paths require full branch coverage.
+8. Mark `@pytest.mark.integration` / `slow`; default CI runs `pytest -m "not slow"`.
+9. **Django**: split settings (`base` / `dev` / `prod` / `test`); list endpoints must `select_related` / `prefetch_related`; put multi-step rules in services + `@transaction.atomic`.
+10. **FastAPI**: routers stay thin; mutations live in services; use Pydantic v2 response models; async routes need async SQLAlchemy (no blocking ORM in `async def`).
+11. Production Django: `DEBUG=False`, secure cookies, HSTS; prod FastAPI schema changes via Alembic—not ad-hoc `create_all`.
+12. Library/API details: **biblos** MCP; repo structure: **atlas** MCP.
+13. Security-sensitive endpoints: **security-review** skill or **exo-security** agent before merge.
+
+## References
+
+| File | Load when |
+|------|-----------|
+| [reference/python-core.md](reference/python-core.md) | Typing, errors, concurrency, packaging, tooling |
+| [reference/python-testing.md](reference/python-testing.md) | pytest fixtures, mocks, async tests, coverage |
+| [reference/django.md](reference/django.md) | Models, DRF, caching, signals, ORM performance |
+| [reference/fastapi.md](reference/fastapi.md) | App factory, DI, Pydantic v2, services, httpx tests |

package/assets/techne/skills/python/reference/django.md

@@ -0,0 +1,104 @@
+# Django and DRF
+
+## Project layout
+
+```
+config/settings/{base,development,production,test}.py
+apps/<domain>/{models,views,serializers,urls,services,tests}
+manage.py
+```
+
+- `base.py`: installed apps, middleware, DB, REST defaults.
+- `production.py`: `DEBUG=False`, TLS cookies, HSTS, structured logging.
+- `test.py`: fast password hasher, in-memory email backend.
+
+## Models and queries
+
+- Custom `QuerySet` methods chained on managers (`active()`, `with_owner()`).
+- Indexes on filter/sort columns; `CheckConstraint` for invariants SQL can enforce.
+- Slug generation in `save()` only when empty.
+
+```python
+class InvoiceQuerySet(models.QuerySet):
+    def open(self):
+        return self.filter(status=Invoice.Status.OPEN)
+
+    def for_tenant(self, tenant_id: int):
+        return self.filter(tenant_id=tenant_id)
+
+class Invoice(models.Model):
+    objects = InvoiceQuerySet.as_manager()
+    tenant = models.ForeignKey("Tenant", on_delete=models.CASCADE)
+    total = models.DecimalField(max_digits=12, decimal_places=2)
+
+    class Meta:
+        indexes = [models.Index(fields=["tenant", "-created_at"])]
+```
+
+List views: `select_related` for FK, `prefetch_related` for M2M/reverse FK.
+
+## DRF
+
+- Separate serializers for read vs create/update when fields differ.
+- ViewSets: set `queryset` with optimizations; swap serializer in `get_serializer_class`.
+- Custom `@action` for non-CRUD operations; keep bodies thin—call services.
+
+```python
+class InvoiceViewSet(viewsets.ModelViewSet):
+    permission_classes = [IsAuthenticated, IsTenantMember]
+    filterset_fields = ["status"]
+    ordering = ["-created_at"]
+
+    def get_queryset(self):
+        return (
+            Invoice.objects.for_tenant(self.request.user.tenant_id)
+            .select_related("tenant")
+        )
+
+    def perform_create(self, serializer):
+        serializer.save(created_by=self.request.user)
+```
+
+## Service layer
+
+```python
+from django.db import transaction
+
+class BillingService:
+    @staticmethod
+    @transaction.atomic
+    def close_invoice(invoice: Invoice) -> Invoice:
+        invoice.status = Invoice.Status.CLOSED
+        invoice.save(update_fields=["status", "updated_at"])
+        LedgerEntry.objects.create(invoice=invoice, amount=invoice.total)
+        return invoice
+```
+
+## Caching
+
+- Per-view: `cache_page` for stable public lists.
+- Low-level: cache keys namespaced by tenant; invalidate on model save signals when needed.
+- Do not cache unbounded querysets—store IDs or paginated slices.
+
+## Signals
+
+- Keep receivers idempotent; defer heavy work to Celery/RQ.
+- Import signals in `AppConfig.ready()`.
+
+## Middleware
+
+- Request timing + structured log line (method, path, status, ms).
+- Avoid ORM writes on every request unless required—prefer async tasks.
+
+## Performance checklist
+
+| Symptom | Fix |
+|---------|-----|
+| N+1 in templates/serializers | prefetch/select |
+| Slow counts | annotate + index, or cached counter |
+| Bulk imports | `bulk_create` / `bulk_update` in batches |
+
+## Security notes
+
+- CSRF on session-auth forms; token auth for SPA APIs as configured.
+- Never expose raw tracebacks in API responses in production.

package/assets/techne/skills/python/reference/fastapi.md

@@ -0,0 +1,118 @@
+# FastAPI
+
+## Layout
+
+```
+app/
+  main.py          # create_app(), lifespan
+  config.py        # pydantic-settings
+  dependencies.py
+  database.py
+  routers/
+  models/          # SQLAlchemy
+  schemas/         # Pydantic v2
+  services/
+tests/conftest.py
+```
+
+## App factory and settings
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    yield
+    await engine.dispose()
+
+def create_app() -> FastAPI:
+    app = FastAPI(title=settings.app_name, lifespan=lifespan)
+    app.include_router(invoices.router, prefix="/invoices", tags=["invoices"])
+    return app
+```
+
+`Settings` via `pydantic_settings.BaseSettings`; load `.env` in dev only—inject secrets from environment in prod.
+
+## Schemas (Pydantic v2)
+
+- `model_config = ConfigDict(from_attributes=True)` on ORM response models.
+- Cross-field rules: `@model_validator(mode="after")`.
+- Separate `Create`, `Update` (`exclude_unset` on patch), and `Read` models.
+
+## Dependencies
+
+```python
+from typing import Annotated
+
+DbSession = Annotated[AsyncSession, Depends(get_session)]
+
+async def current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: DbSession,
+) -> User:
+    ...
+```
+
+Type aliases (`DbSession`, `ActiveUser`) reduce router noise.
+
+## Routers
+
+- Always set `response_model` and explicit status codes.
+- Map domain errors to `HTTPException` or registered handlers—401 vs 403 must differ.
+- Pagination: `Query(ge=0)` / `le=100`; **stable `order_by` column** on every offset query.
+
+## Services and transactions
+
+```python
+class InvoiceService:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def create(self, payload: InvoiceCreate) -> Invoice:
+        row = Invoice(**payload.model_dump())
+        self.db.add(row)
+        try:
+            await self.db.commit()
+        except IntegrityError as exc:
+            await self.db.rollback()
+            raise DuplicateInvoiceError from exc
+        await self.db.refresh(row)
+        return row
+```
+
+Unique constraints belong in the database; catch `IntegrityError` instead of check-then-insert races.
+
+## Async rules
+
+- Use `AsyncSession` + `await session.execute(select(...))`.
+- Blocking libraries → thread pool or swap library.
+
+## Testing (httpx)
+
+```python
+@pytest_asyncio.fixture
+async def client(db_session):
+    app = create_app()
+    app.dependency_overrides[get_session] = lambda: _override(db_session)
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as ac:
+        yield ac
+```
+
+Override DB and auth dependencies; use in-memory SQLite (`aiosqlite`) or test container per project policy.
+
+## Lifespan vs migrations
+
+- Dev-only: metadata `create_all` in lifespan is acceptable for demos.
+- Production: Alembic (or equivalent) owns schema; lifespan only opens/closes pools.
+
+## Anti-patterns
+
+| Bad | Good |
+|-----|------|
+| ORM logic in route | service method |
+| sync `Session` in async route | AsyncSession |
+| returning ORM model directly | response schema |
+| unbounded list endpoints | limit + sort + filters |