devstack 0.1.0

package/vendor/skills/skills/drizzle-safe-migrations/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: drizzle-safe-migrations
+description: Production-safe Drizzle migration workflow for schema changes that require data backfills or constraint tightening. Use when changing enums/check constraints/defaults, removing status values, or sequencing custom and generated migrations in Drizzle. Trigger on requests about Drizzle migration safety, deployment-safe backfills, migration ordering, and rollback planning.
+---
+
+# Drizzle Safe Migrations
+
+## Overview
+
+Use this skill to run database migrations in a way that is auditable, deployment-safe, and consistent with Drizzle's migration model.
+
+## Core Rules
+
+- Always generate schema migrations with the project script (`bun run db:generate`).
+- Never hand-edit generated schema migration files.
+- Generate data backfills as custom migrations (`bun run db:generate -- --custom --name <name>`) and edit only that custom SQL file.
+- Apply data normalization before tightening constraints.
+- Keep one-off data fixes in migration history, not as hidden runtime logic, unless an emergency hotfix requires temporary mitigation.
+
+## Workflow
+
+1. Classify the change:
+   - `schema-only`: only column/table/index/default changes.
+   - `data+schema`: old rows must be transformed before new constraints/defaults.
+2. For `data+schema`, create custom migration first:
+   - `bun run db:generate -- --custom --name <descriptive_name>`
+   - Add idempotent backfill SQL.
+3. Generate schema migration second:
+   - `bun run db:generate`
+4. Verify migration ordering in `drizzle/meta/_journal.json`:
+   - backfill migration index must be lower than constraint-tightening migration index.
+5. Verify generated SQL and snapshots:
+   - backfill migration contains only intended data change.
+   - schema migration contains constraint/default/type changes.
+6. Run full backend verification:
+   - `bun run lint && bun run typecheck && bun run test`
+7. Document deployment notes:
+   - expected data transformations,
+   - lock-risk areas,
+   - rollback strategy.
+
+## Backfill Requirements
+
+- Use restrictive `WHERE` clauses.
+- Prefer idempotent updates (`UPDATE ... WHERE status = 'legacy_value'`).
+- Do not mix unrelated DDL/DML in the same migration.
+- Keep SQL explicit and minimal.
+
+## Constraint Tightening Pattern
+
+When removing allowed values (enum/check):
+
+1. Backfill existing rows to valid target value.
+2. Update default to new value.
+3. Tighten check/enum constraint.
+
+For large tables or strict uptime targets, use staged PostgreSQL patterns (`NOT VALID` + `VALIDATE CONSTRAINT`) where applicable.
+
+## Anti-Patterns
+
+- Hand-editing generated schema migration files.
+- Tightening constraints before backfilling existing data.
+- Hiding one-time migration logic in app startup code without migration artifacts.
+- Running migrations without validating order in the Drizzle journal.
+
+## Reference
+
+- See `references/production-playbook.md` for command templates and review checklists.

package/vendor/skills/skills/drizzle-safe-migrations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Drizzle Safe Migrations"
+  short_description: "Guide safe Drizzle schema/data migration rollouts"
+  default_prompt: "Use $drizzle-safe-migrations to plan and execute a safe Drizzle migration with backfills and constraint changes."

package/vendor/skills/skills/drizzle-safe-migrations/references/production-playbook.md

@@ -0,0 +1,47 @@
+# Drizzle Production Migration Playbook
+
+## Decision Tree
+
+- If no existing data can violate new constraints: use generated schema migration only.
+- If existing data may violate new constraints: use custom backfill migration first, then generated schema migration.
+
+## Command Sequence
+
+```bash
+# 1) Create custom backfill migration
+bun run db:generate -- --custom --name <backfill_name>
+
+# 2) Edit generated custom file in drizzle/
+# Example: drizzle/0014_<backfill_name>.sql
+
+# 3) Generate schema migration
+bun run db:generate
+```
+
+## Example Backfill SQL
+
+```sql
+UPDATE "tasks"
+SET "status" = 'pending'
+WHERE "status" = 'saved';
+```
+
+## Migration Review Checklist
+
+- Backfill migration is ordered before schema-tightening migration.
+- Custom migration changes only the intended rows.
+- Schema migration removes legacy values from constraints/enums.
+- Defaults reflect the new target value.
+- `drizzle/meta/_journal.json` and snapshots are present.
+
+## Deployment Checklist
+
+- Confirm backups/snapshots are available.
+- Apply migrations in order in staging first.
+- Validate row counts before and after backfill.
+- Run app smoke checks after migration.
+
+## Rollback Strategy
+
+- Prefer forward-fix migrations instead of editing old migration files.
+- If rollback is necessary, add a new migration that reintroduces valid compatibility states.

package/vendor/skills/skills/effect-ts/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: effect-ts
+description: Expert guide for writing Effect-TS code, including project setup, core principles, data modeling with Schema, error handling, and the Context.Tag service pattern. Use when writing, refactoring, or analyzing TypeScript code using the Effect library.
+allowed-tools: Read, Grep, Glob
+---
+
+# Effect-TS Developer Guide
+
+Guidelines, patterns, and best practices for Effect-TS in this project.
+
+## Reference Documents
+
+Read the relevant reference before writing code. `references/core-patterns.md` is the master index.
+
+| Reference                                     | Topics                                                                                                                                |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/foundations.md`                   | Setup, imports, TypeScript config                                                                                                     |
+| `references/construction-and-style.md`        | `Effect.gen`, `pipe`, `Effect.fn`, `Effect.fnUntraced`                                                                                |
+| `references/schema-errors-config.md`          | Schema modeling, errors, config, retry                                                                                                |
+| `references/pattern-matching.md`              | **`Match.type`, `Match.value`, `Match.tag`, `Match.exhaustive`** — mandatory for tagged unions                                        |
+| `references/control-flow-and-runtime.md`      | `Effect.if`, `Effect.when`, loops, `runSync`, `runPromise`, `ManagedRuntime`                                                          |
+| `references/data-types.md`                    | **All data types**: `Option`, `Either`, `Data`, `Exit`, `Cause`, `Duration`, `DateTime`, `BigDecimal`, `Chunk`, `HashSet`, `Redacted` |
+| `references/data-and-testing.md`              | Option/Either/Array quick ref, `@effect/vitest` setup                                                                                 |
+| `references/concurrency-and-resources.md`     | Concurrency, `Scope`, finalizers, resources                                                                                           |
+| `references/streams-deep-dive.md`             | Creating, operations, grouping, partitioning, broadcasting, buffering, throttling, error handling                                     |
+| `references/sink.md`                          | Sink constructors, collecting, folding, operations, concurrency, leftovers, `Stream.transduce`                                        |
+| `references/batching-and-caching.md`          | Request batching (`RequestResolver`), `cachedWithTTL`                                                                                 |
+| `references/schema-transforms-and-filters.md` | `Schema.transform`, `Schema.filter`, refinements                                                                                      |
+| `references/api-platform-observability.md`    | `HttpApi`, logging, tracing, spans                                                                                                    |
+| `references/class-patterns.md`                | `Context.Tag` service pattern, layers, memoization, testing                                                                           |
+| `references/error-handling-patterns.md`       | `Data.TaggedError`, `Schema.TaggedError`, error composition, recovery                                                                 |
+| `references/library-development-patterns.md`  | Forbidden patterns, `Effect.fn` vs `Effect.fnUntraced`, resource management                                                           |
+| `references/testing-patterns.md`              | `@effect/vitest` with `assert`, `TestClock`, service mocking                                                                          |
+| `references/quality-tooling-and-resources.md` | Anti-patterns, validation checklist, packages                                                                                         |
+
+## Core Principles
+
+1. **Effect is not just for async** — Use `Effect` for any fallible operation
+2. **Immutability** — Use Effect's immutable data structures (`Data`, `Chunk`, `HashSet`)
+3. **Type Safety** — Track errors in types. No `any` or `unknown` in error channels
+4. **Composition** — Build programs by composing small Effects
+5. **Schema-First** — Define data models using `Schema` with branded types
+6. **Pattern Matching** — Use `Match` for all branching over tagged unions (never `switch`/`if-else` on `_tag`)
+7. **Effect Data Types** — Use `Option` (not null), `Either` (not ad-hoc), `Duration` (not raw ms), `DateTime` (not Date), `BigDecimal` (not floats), `Redacted` (for secrets). See `references/data-types.md`
+
+## Quick Reference
+
+### Import Convention
+
+```typescript
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as Either from "effect/Either";
+import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
+import { pipe } from "effect/Function";
+// Also: DateTime, BigDecimal, Chunk, HashSet, Exit, Cause, Redacted
+```
+
+### Effect.gen vs pipe vs Effect.fn
+
+```typescript
+// Effect.gen — complex logic with branching
+Effect.gen(function* () {
+  const user = yield* fetchUser(id);
+  if (user.isAdmin) yield* logAdminAccess(user);
+  return user;
+});
+
+// pipe — linear transformations
+pipe(fetchData(), Effect.map(transform), Effect.flatMap(save));
+
+// Effect.fn — traced reusable functions (public API)
+const processUser = Effect.fn("processUser")(function* (userId: string) {
+  const user = yield* getUser(userId);
+  return yield* processData(user);
+});
+```
+
+### Error Handling
+
+`Data.TaggedError` for in-process discrimination, `Schema.TaggedError` for serializable errors. See `references/error-handling-patterns.md`.
+
+```typescript
+export class NotFoundError extends Data.TaggedError("NotFoundError")<{
+  id: string;
+}> {}
+
+// Recovery
+pipe(
+  riskyOp,
+  Effect.catchTag("NotFoundError", e => Effect.succeed(null))
+);
+```
+
+### Pattern Matching (Mandatory for Tagged Unions)
+
+**Always use `Match`** — `Match.exhaustive` catches missing cases at compile time. See `references/pattern-matching.md`.
+
+```typescript
+// Match.type — reusable matcher function
+const handle = Match.type<Status>().pipe(
+  Match.tag("Pending", s => `Pending since ${s.requestedAt}`),
+  Match.tag("Approved", s => `Approved by ${s.approvedBy}`),
+  Match.exhaustive // Compile error if any variant is missing
+);
+
+// Match.valueTags — shorthand for immediate matching
+Match.valueTags(status, {
+  Pending: s => `Pending since ${s.requestedAt}`,
+  Approved: s => `Approved by ${s.approvedBy}`,
+});
+```
+
+### Service Pattern (Context.Tag)
+
+See `references/class-patterns.md` for full pattern with factory methods and layers.
+
+```typescript
+export class MyService extends Context.Tag("@myapp/MyService")<
+  MyService,
+  { readonly find: (id: string) => Effect.Effect<Result, NotFoundError> }
+>() {
+  static readonly layer = Layer.effect(
+    MyService,
+    Effect.gen(function* () {
+      const db = yield* Database;
+      return MyService.of({ find: MyService.createFind(db) });
+    })
+  );
+}
+```
+
+### Testing
+
+**CRITICAL**: Use `assert` from `@effect/vitest` for `it.effect`. Never `expect` with `it.effect`. See `references/testing-patterns.md`.
+
+```typescript
+import { assert, describe, it } from "@effect/vitest";
+
+it.effect("processes data", () =>
+  Effect.gen(function* () {
+    const result = yield* processData("input");
+    assert.strictEqual(result, "expected");
+  }).pipe(Effect.provide(MyService.testLayer))
+);
+```
+
+## Forbidden Patterns
+
+```typescript
+// NEVER: try-catch in Effect.gen — use Effect.exit instead
+Effect.gen(function* () {
+  try {
+    yield* someEffect;
+  } catch (e) {} // WRONG — will never catch
+});
+
+// NEVER: Type assertions
+const value = something as any; // FORBIDDEN
+const value = something as never; // FORBIDDEN
+
+// NEVER: Missing return on terminal yield
+Effect.gen(function* () {
+  if (bad) {
+    yield* Effect.fail("err");
+  } // Missing return!
+});
+
+// NEVER: switch/if-else on _tag — use Match instead
+switch (status._tag /* no exhaustiveness checking! */) {
+}
+
+// NEVER: Effect.runSync inside Effects
+Effect.gen(function* () {
+  Effect.runSync(sideEffect);
+}); // Loses error tracking
+
+// NEVER: Native JS where Effect data types exist
+const x: string | null = null; // Use Option<string>
+const delay = 5000; // Use Duration.seconds(5)
+const now = new Date(); // Use DateTime.now or DateTime.unsafeNow()
+const price = 0.1 + 0.2; // Use BigDecimal for precision
+const secret = "sk-1234"; // Use Redacted.make("sk-1234")
+
+// NEVER: expect with it.effect
+it.effect("test", () =>
+  Effect.gen(function* () {
+    expect(result).toBe(value); // WRONG — use assert.strictEqual
+  })
+);
+
+// NEVER: Inline layers (breaks memoization)
+Layer.provide(Postgres.layer({ url })); // Store in constant instead
+```
+
+## Validation Checklist
+
+- [ ] Imports use `import * as Module from "effect/Module"`
+- [ ] `Effect.gen` for complex logic, `pipe` for linear, `Effect.fn` for public API
+- [ ] `Match` for all `_tag` branching with `Match.exhaustive`
+- [ ] Branded types for domain primitives (IDs, Emails)
+- [ ] Errors: `Data.TaggedError` (discrimination) or `Schema.TaggedError` (serializable)
+- [ ] No `any`/`unknown` in error channels, no type assertions
+- [ ] No try-catch in `Effect.gen` — use `Effect.exit`
+- [ ] `return yield*` for terminal effects (`Effect.fail`, `Effect.interrupt`)
+- [ ] Services: `Context.Tag` with static factory methods and `Effect.fn` tracing
+- [ ] Layers: `Layer.merge`/`Layer.provide`, parameterized layers in constants
+- [ ] Resources: `Effect.acquireRelease` or `Effect.scoped`
+- [ ] `Option` for nullable values, `Either` for sync success/failure
+- [ ] `Duration` for time values, `DateTime` for dates (not `Date`)
+- [ ] `BigDecimal` for financial/precise math, `Redacted` for secrets
+- [ ] `Data.struct`/`Data.Class` for structural equality, `HashSet` for sets
+- [ ] `Clock.currentTimeMillis` instead of `Date.now()`
+- [ ] Tests: `assert` from `@effect/vitest` (not `expect`) with `it.effect`
+- [ ] Run `pnpm run typecheck` and `pnpm run test`
+
+## Reference Implementation
+
+See `/packages/looper/src/data/api-client/api-client.ts` for Context.Tag service pattern.
+
+## Effect Solutions CLI
+
+```bash
+pnpm exec effect-solutions list              # List all topics
+pnpm exec effect-solutions show <slug...>    # Read topics
+pnpm exec effect-solutions search <term>     # Search by keyword
+```

package/vendor/skills/skills/effect-ts/references/api-platform-observability.md

@@ -0,0 +1,194 @@
+# HttpApi, Platform, and Observability
+
+Schema-driven HTTP APIs, platform services, and tracing/logging practices.
+
+## HttpApi Architecture (Schema-Driven APIs)
+
+Use `HttpApi` to define type-safe, schema-driven API contracts. This replaces manual `HttpClient` usage for defining service boundaries.
+
+### Defining an API
+
+```typescript
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "@effect/platform";
+import { Schema } from "effect";
+
+// Define the API
+class UsersApi extends HttpApiGroup.make("users")
+  .add(
+    HttpApiEndpoint.get("getUser", "/users/:id")
+      .addSuccess(Schema.Struct({ id: Schema.Number, name: Schema.String }))
+      .addError(Schema.NotFound)
+  )
+  .add(
+    HttpApiEndpoint.post("createUser", "/users")
+      .setPayload(Schema.Struct({ name: Schema.String }))
+      .addSuccess(Schema.Struct({ id: Schema.Number, name: Schema.String }))
+  ) {}
+
+// Export the API definition
+export class MyApi extends HttpApi.make("my-api").add(UsersApi) {}
+```
+
+### Consuming an API
+
+```typescript
+import { HttpApiClient } from "@effect/platform";
+
+const program = Effect.gen(function* () {
+  const client = yield* HttpApiClient.make(MyApi, {
+    baseUrl: "https://api.example.com",
+  });
+
+  // Type-safe method calls
+  const user = yield* client.users.getUser({ path: { id: 1 } });
+});
+```
+
+## Platform Integration
+
+### HTTP Client
+
+```typescript
+import * as HttpClient from "@effect/platform/HttpClient";
+
+const fetchUser = (id: string) =>
+  pipe(
+    HttpClient.get(`https://api.example.com/users/${id}`),
+    Effect.flatMap(response => response.json),
+    Effect.flatMap(Schema.decode(User)),
+    Effect.scoped
+  );
+```
+
+### Platform Services
+
+```typescript
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+
+// Run with Node runtime
+NodeRuntime.runMain(program.pipe(Effect.provide(NodeContext.layer)));
+```
+
+## Logging & Observability
+
+### Log Functions
+
+```typescript
+import * as Effect from "effect/Effect";
+
+yield * Effect.log("Info message"); // INFO level (default)
+yield * Effect.logDebug("Debug message"); // DEBUG (hidden by default)
+yield * Effect.logInfo("Info message"); // INFO
+yield * Effect.logWarning("Warning message"); // WARNING
+yield * Effect.logError("Error message"); // ERROR
+yield * Effect.logFatal("Fatal message"); // FATAL
+
+// Log multiple messages
+yield * Effect.log("msg1", "msg2", "msg3");
+
+// Log with Cause context
+yield * Effect.log("Operation failed", Cause.die("Oh no!"));
+```
+
+Default logger output format:
+
+```
+timestamp=... level=INFO fiber=#0 message="Application started"
+```
+
+### Log Levels
+
+By default, DEBUG messages are hidden. Adjust with `Logger.withMinimumLogLevel`:
+
+```typescript
+import * as Logger from "effect/Logger";
+import * as LogLevel from "effect/LogLevel";
+
+// Enable DEBUG logs for a specific scope
+const debugTask = myEffect.pipe(Logger.withMinimumLogLevel(LogLevel.Debug));
+
+// Available levels (in order): All, Trace, Debug, Info, Warning, Error, Fatal, None
+```
+
+### Custom Loggers
+
+Replace the default logger:
+
+```typescript
+// Simple console logger
+const simpleLogger = Logger.replace(
+  Logger.defaultLogger,
+  Logger.make(({ message }) => console.log(message))
+);
+
+const program = myEffect.pipe(Effect.provide(simpleLogger));
+
+// Pretty logger (built-in)
+const pretty = myEffect.pipe(Effect.provide(Logger.pretty));
+
+// JSON logger (built-in)
+const json = myEffect.pipe(Effect.provide(Logger.json));
+```
+
+### Log Annotations
+
+Add structured metadata to log entries:
+
+```typescript
+// Annotate specific scope
+const annotated = myEffect.pipe(
+  Effect.annotateLogs("userId", userId),
+  Effect.annotateLogs("requestId", requestId)
+);
+// Output: timestamp=... level=INFO ... userId=abc123 requestId=xyz message="..."
+
+// Annotate with record
+const annotated2 = myEffect.pipe(Effect.annotateLogs({ module: "auth", action: "login" }));
+```
+
+### Log Spans (Timing)
+
+Measure how long a section takes:
+
+```typescript
+const timed = myEffect.pipe(Effect.withLogSpan("fetchUser"));
+// Output: timestamp=... level=INFO ... message="Done" span=fetchUser=150ms
+```
+
+### Tracing & Spans
+
+```typescript
+// Add OpenTelemetry-compatible spans
+const traced = pipe(
+  fetchUser(userId),
+  Effect.withSpan("fetch-user", {
+    attributes: { userId },
+  }),
+  Effect.tap(user => Effect.logInfo("User fetched", { user: user.email }))
+);
+
+// Annotate the current span
+yield * Effect.annotateCurrentSpan("result.count", results.length);
+
+// Nested spans
+const program = Effect.gen(function* () {
+  const user = yield* fetchUser(id).pipe(Effect.withSpan("fetch-user"));
+  const orders = yield* fetchOrders(user.id).pipe(Effect.withSpan("fetch-orders"));
+  return { user, orders };
+}).pipe(Effect.withSpan("get-user-with-orders"));
+```
+
+### OpenTelemetry Integration
+
+```typescript
+import { NodeSdk } from "@effect/opentelemetry";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+
+const TracingLayer = NodeSdk.layer(() => ({
+  resource: { serviceName: "my-service" },
+  spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter()),
+}));
+
+const main = program.pipe(Effect.provide(TracingLayer));
+```