Skills

Synthesized cross-build conventions that auto-load on the factory-* namespace. You don’t call them by hand — they activate when the work matches.

• factory-api — API conventions for both server actions and tRPC builds. Covers the decision between them, per-mutation Zod input schemas, central router composition, pagination shape, multi-field search via Drizzle ilike + or(), mutation lifecycle hooks, conditional query enabling, stale-time defaults, error response shape and custom error class taxonomy, mutation-boundary audit logging, fetch adapter for tRPC routes. Read when designing or implementing any data-mutation endpoint.
• factory-auth — Auth and authorization conventions distilled across builds with three different auth stacks (Better Auth + orgs, Supabase Auth + RLS, Clerk). Covers the provider decision matrix, the unified wrapper interface (requireAuth / requireRole / withOrgContext), procedure tier stacking, session handling, OAuth callback safety, plugin composition with Better Auth, and the anti-patterns (hardcoded allowlists, admin client at module scope, triple-fallback auth surfaces).
• factory-ci — CI and pull-request review conventions. One canonical .github/workflows/ci.yml is the merge gate (typecheck, lint, test, build, claude-review); branch protection’s required-checks list matches the job list 1:1; anthropics/claude-code-action@v1 reviews every PR against the factory-pitfalls.md checklist as a required check, not advisory. Deploy workflows live separately and never gate merge. Read at project kickoff and whenever wiring CI on a new repo.
• factory-commits — Commit message and branch convention — Conventional Commits format with a Linear issue reference required in subject or body. Includes the canonical commitlint.config.cjs, Husky hook snippet, and opencommit configuration. Read whenever setting up a new project or wiring AI-assisted commits.
• factory-data-layer — Database schema, ORM, and migration conventions across builds. Drizzle as default with domain-partitioned schema modules, shared timestamps helper, multi-tenancy keys with cascade delete, pgTableCreator prefixing, JSONB for flexible attributes, schema-derived type exports, polymorphic table patterns, ESLint Drizzle rules. Covers when to escape to raw SQL or Supabase auto-types.
• factory-data-pipelines — Data ingestion and pipeline conventions for projects that import CSVs, run simulations, or operate Python services alongside Next.js. Covers Papa Parse for CSV imports, JSONB envelope storage for time-series data, the three-entry-point Python service pattern (CLI / Cloud Run API / Pub/Sub), YAML config for service-level data, geopandas/shapely for geospatial work, and deployment via Cloud Run + ephemeral Neon DBs.
• factory-db-migration — The operational discipline for running a destructive change against a production database — schema migrations, data backfills, one-shot RPCs, historical seed imports. Adjacent to factory-data-layer.md (schema design) and factory-deployment.md (where migrations execute in CI) — this skill is about the runbook around the act of mutating prod. Covers the three-stage write contract (preflight → mutate → verify → rollback), idempotency by natural key, layered backup independence (Layer C from factory-security.md / KAI-126 doctrine), human-gated execution, bidirectional update semantics, validation-at-parse-not-at-constraint, and the failure modes a senior DB engineer pattern-matches before opening a migration PR.
• factory-deployment — Deployment and infrastructure conventions across builds. Vercel + Neon for web (with PR branch DBs), Cloud Run for Python services (one service per entry-point variant), GitHub Actions matrix-deploy on merge, Terraform with environments/modules layout for AWS / compliance customers, RDS IAM authentication for AWS DBs, Docker per Python entry point, env vars via t3-oss/env-nextjs, and the single-tenant customer-cloud deployment model (per the factory thesis). Migrations in CI, never at runtime.
• factory-design — Design-system discipline distilled across builds. Semantic token vocabulary (name intent, not palette position), CSS variables bridged into Tailwind, dark/light as a variable swap, single- vs two-layer token systems, component primitives as token consumers, when to promote a repeated utility cluster into a primitive, and the vocabulary-sprawl failure mode. Read whenever you touch styling — marketing surface, internal app, or design-system repo. Paired with factory-frontend, which delegates here for visual coherence.
• factory-forms — Form conventions distilled across builds. react-hook-form + Zod via resolver (Mantine or shadcn variant), three Zod schema variants (server strict / client lenient / patch), drawer-CRUD with mode union, field-registry pattern for multi-step forms, declarative conditional visibility with auto-cleanup, debounced auto-save with dirty tracking, masked inputs for sensitive fields with KMS encryption-at-rest, dynamic field arrays with constraints, S3 presigned-URL upload flow. Read when scaffolding any form — single-step CRUD or multi-step complex intake.
• factory-frontend — Frontend conventions distilled across builds. CRUD shape (DataTable + drawer with mode union), RowActions primitive, format helpers, heading tiers, semantic color tokens, query-key naming, component-library decision criteria (Mantine vs shadcn). Read when scaffolding any UI surface that touches lists, forms, or entity editing.
• factory-llm-workflows — LLM workflow conventions distilled from production agent/RAG work. Covers LangGraph TypedDict state schemas, node factory closures, conditional edge routing, structured output via JSON schema, prompt fallback patterns with optional PromptHub override, hybrid search with confidence gating + fallback supplement, SSE streaming with event dispatch, hexagonal ports/adapters when scale justifies. Read when building any LLM-driven workflow with state, tool calls, or streaming UX.
• factory-observability — Observability conventions across builds. PostHog + Sentry on day one (non-negotiable per the factory thesis — easiest to start early, most expensive to backfill). Request tracing with propagated trace IDs, structured logging, activity-log audit table, event tagging by tool/feature for per-tool usage queryability, PostHog ingest-URL rewrite to avoid ad-blocker breakage. What to log, what NOT to log (PII).
• factory-pitfalls — Cross-skill index of observed failure modes. Each skill carries its own Failure mode blocks under the Principle they violated; this file is the flat scan across all of them, plus process-level pitfalls that don’t have a skill home. Read at project kickoff and during code review.
• factory-prompting — Structured prompting with XML tags. A small named vocabulary (instructions, context, input, output_format, examples, constraints, role, thinking) that turns a prose ask into something the model can parse without ambiguity. Read whenever you’re authoring a prompt by hand, designing a prompt template for production, or rewriting a flaky ask. Paired with /prompt, which converts a rough ask into the structured form.
• factory-security — Security conventions for builds that touch sensitive data, regulated industries, or AI-generated code paths. Covers KMS encryption at rest, BAA verification for PHI in email/SMS, safe URL redirects, admin-client bypass guardrails, in-memory rate-limiter caveats, the “read-only by default” stance for AI-generated code, mandatory-review-queue pattern, and request tracing for support workflows.
• factory-stack — Cross-build locked stack decisions and decision criteria for divergent choices. Read at the start of any new project. Covers runtime, language, ORM, auth provider, component library, deployment, and observability — what’s a hard pick, what depends on context, and the criteria for context-driven picks.
• factory-testing — Testing conventions across builds. Vitest + Playwright as the locked stack; tests co-located in __tests__ next to the code they verify; shared test primitives (provider wrappers, mock factories) centralized in src/lib/test-utils.tsx; coverage thresholds enforced at the merge gate (CI ownership lives in factory-ci.md). Read at project kickoff and whenever you write or review a test.
• factory-verification — How we know the software the factory produces is correct, and how we know the kit’s own conventions are followed. Defines the four-tier eval spectrum (CLI rule / test / agent / human gate), the rule that evals graduate downward to their cheapest home, the banded coverage score with severity-aware disclosure, and the delta-gated GitHub Action that guards the PR boundary without disrupting the inner loop. The recipe locks to factory-kit-check + GitHub Actions; the principles are stack-agnostic. Read at project kickoff, when wiring the conformance gate, and whenever asking “how do we know the agent did this right?”
• factory-voice — Communication voice for Claude Code — senior software architect, first-principles framing, crisp English. Governs how Claude writes to Linear (issue comments, summaries, status updates), commits, PRs, and how it talks in terminal sessions. Read on session start and before any external write.