factory-stack
Skill9 starsChanged 4 months agoMITView on GitHub
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.
In this repository42 other files it gives its agents.
- guidance/claude.mdCLAUDE.md
- factory-animationSkill
- factory-api-route-engineerSkill
- factory-apiSkill
- factory-authSkill
- factory-auth-wiring-specialistSkill
- factory-ciSkill
- factory-closeSkill
- factory-code-reviewerSkill
- factory-commitsSkill
- factory-data-layerSkill
- factory-data-pipeline-engineerSkill
- factory-data-pipelinesSkill
- factory-db-migration-engineerSkill
- factory-db-migrationSkill
- factory-db-schema-architectSkill
- factory-deploymentSkill
- factory-designSkill
- factory-entrySkill
- factory-feature-architectSkill
- factory-forms-builderSkill
- factory-formsSkill
- factory-frontend-engineerSkill
- factory-frontendSkill
- factory-kit-auditSkill
- factory-llm-workflow-engineerSkill
- factory-llm-workflowsSkill
- factory-observabilitySkill
- factory-pitfallsSkill
- factory-promptingSkill
- factory-promptSkill
- factory-releaseSkill
- factory-security-engineerSkill
- factory-securitySkill
- factory-setup-linearSkill
- factory-standupSkill
- factory-state-modelingSkill
- factory-submitSkill
- factory-testingSkill
- factory-verification-engineerSkill
- factory-verificationSkill
- factory-voiceSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 42
Pitfall: don't import both. Pick a side per project.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Factory stack
Locked decisions (no per-project relitigation)
| Layer | Choice | Why |
| Runtime | Next.js App Router | Convergent across all customer repos; ecosystem fit for tRPC / server actions / Vercel deploy |
| Language | TypeScript | Convergent; non-negotiable |
| Validation | Zod | Pairs with both tRPC and server actions; field registry pattern depends on it |
| Server state | TanStack Query | Convergent across all repos that need server state |
| DB | Postgres via Neon (dev branches) or RDS (compliance) | Convergent |
| Forms | react-hook-form + Zod via resolver | Convergent |
| Resend | Convergent | |
| Linting | ESLint + Prettier + ESLint Drizzle rules where applicable | Convergent |
| Env vars | t3-oss/env-nextjs (Zod-validated, server/client split) | Convergent |
Decision-criteria choices (pick per project; document in project's CLAUDE.md or DECISIONS.md)
ORM — Drizzle vs Supabase auto-types vs raw pg
- Drizzle — default. Schema partitioning by domain (
_shared.ts,<domain>.ts) + sharedtimestampshelper.pgTableCreator()for prefixing if the DB is shared. - Supabase auto-generated types — when Supabase Auth + RLS is already doing real work. RLS policies are the contract; auto-types are a free byproduct.
- Raw
pg— never for new projects. Migrate if encountered.
Auth — Better Auth + orgs vs Supabase Auth + RLS vs Clerk
- Better Auth + organization plugin — default. Org + RBAC + 2FA out of the box; pairs with Drizzle.
- Supabase Auth + RLS — when RLS pays for itself (multi-role partner/distributor model, deeply branched authz at row level).
- Clerk — consumer/SSO-heavy, or when managed auth UI components matter.
The wrapper interface is the same regardless: requireAuth(), requireRole(), withOrgContext(). See factory-auth.md (Phase B) for the canonical wrapper shape.
API style — server actions vs tRPC
- Server actions — default for feature-folder-colocated apps with one frontend consumer. Pairs with TanStack Query (
useMutationwrapping the action). - tRPC — when typed RPC contracts add leverage: ≥3 entities with cross-feature queries, multiple consumers, or a public API surface.
- Pitfall: don't import both. Pick a side per project.
Component library — Mantine vs shadcn
- Mantine — CRUD-heavy / form-table dense / internal-tool surfaces. Built-in date pickers, multiselects, notifications save weeks. Pair with
mantine-form-zod-resolver. - shadcn — design flexibility / marketing-adjacent / unified Tailwind styling with a landing site. Pair with
react-hook-form+zodResolver. - Same project, one choice. Mixing leads to design drift.
Deploy
- Web (Next.js): Vercel. PR previews via Neon dev branches in GitHub Actions.
- Python services: Cloud Run. CLI / Cloud Run API / Pub/Sub handler — see
factory-data-pipelines.md. - Infra-as-code: Terraform with environments/modules layout when AWS/RDS or HIPAA/FDA compliance is in play; skip when Vercel + Neon is sufficient.
Observability
- PostHog + Sentry from day one. Non-negotiable. Easiest to start early, most expensive to backfill.
- Tag events by tool/feature so per-tool usage is queryable later.
- See
factory-observability.md(Phase B) for activity logging and trace ID patterns.
How to use this skill
- At project kickoff, read this file end-to-end.
- For decision-criteria choices, make the pick explicitly in the project's
CLAUDE.mdor a one-pageDECISIONS.md(one line per decision). - Refer back when the project considers changing course — the criteria are the basis for that conversation.
Pitfalls referenced elsewhere
See factory-pitfalls.md for the anti-patterns digest indexed across all factory-*.md skills.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.