@nonlinear-labs/factory-kit

factory-kit

This is the foundation for a "software factory" - Claude skills, agents, and slash commands that are all automatally symlinked into ~/.claude/. This allows you to pull upon these skills in any repository.

Why this exists

This repository is a synthesis of learnings across multiple production builds. In each one, I went through a learning journey to understand how to build a production-ready stack. Over countless hours, I tried to understand when and when not to implement specific components. Now, I've pulled my learnings into a set of skills & agents that I can use whenever I start a new project.

This is also becoming a public record of how I am iterating towards a "software factory". Over time, as more code gets generated, I believe the differentiating layer will be the architectural decisions that get made during the build. I want to codify as many of these as I can throughout my journey so that I can consistently come back to them.

Structure — principles-first, stack-locked recipes

Each factory-*.md skill leads each section with the Principle (one sentence, stack-agnostic), then Why (constraint → option → tradeoff), then Recipe (the Next.js / Drizzle / Better Auth / Mantine / Cloud Run shape we use), and a Failure mode block when there's one to name. A reader on a different stack can read the principle and why of any section and skip the recipe. The kit is opinionated on the recipe layer and shareable on the principle layer — by structure, not by separate files.

Layout

factory-kit/
├── skills/                # synthesized factory-*.md docs, auto-loaded as ~/.claude/skills/
├── agents/                # specialist subagents, callable via the Agent tool
├── commands/              # slash commands (/standup, /entry, /submit, /close, /release, /setup-linear, /prompt, /kit-audit)
├── check/                 # factory-kit-check — deterministic rule engine (TS source)
├── bin/                   # factory-kit (installer) + factory-kit-check (the checker)
├── CLAUDE.md              # user-level header listing the rosters above
├── commitlint.config.cjs  # kit's own commitlint (Conventional Commits, no Linear-ID rule)
├── VERSION
└── install.sh             # per-file symlinks into ~/.claude/{skills,agents,commands}

Install

npx @nonlinear-labs/factory-kit

That's it. The CLI symlinks all skills, subagents, commands, and the user-level CLAUDE.md into ~/.claude/. Restart Claude Code and the kit auto-loads in every project.

npx @nonlinear-labs/factory-kit is idempotent — re-run anytime. Existing files at destinations are skipped with a warning; symlinks pointing into the cached package are refreshed.

Or install from a local clone

# pin to a release (recommended)
git checkout v0.1.5
./install.sh

# or track HEAD (moving edge)
git checkout main
./install.sh

The shell installer and the npx CLI do the same thing; pick whichever fits the workflow.

factory-kit-check — enforce the standard

The skills describe the conventions. factory-kit-check enforces a deterministic subset of them. Point it at a repo; it walks the code, runs a rule set, and prints findings — each one citing the factory-pitfalls.md entry it violates.

factory-kit-check                 # check the current directory
factory-kit-check ../some-repo    # check another repo

It is read-only — it reads and judges, it never writes to your code. It exits non-zero on any critical/high finding, so it drops straight into a pre-push hook or CI step.

Why deterministic (not an LLM): the rules are cheap, reproducible, and cost nothing per run, so you can run them on every save without thinking about it. Each rule is greppable code with a documented heuristic and a citation — no black box.

Rules (v0)

Rule	Severity	Cites
admin-client-module-scope	critical	factory-auth.md §Admin client — always wrapped
hardcoded-email-allowlist	critical	factory-auth.md §Hardcoded email allowlists
public-procedure-mutation	critical	factory-auth.md §Auth from day one
update-delete-no-where	critical	factory-data-layer.md §ORM pick
in-memory-rate-limiter	high	factory-security.md §Rate limiting
mixed-trpc-server-actions	high	factory-api.md §API style — pick one

Detection is regex/line-heuristic in v0 — precision-first, tuned against real repos. Rules are language-tagged (TS today; the seam for a Python ast sidecar is in place) and the report footer lists how many known pitfalls are not yet covered, so the tool never implies full coverage.

Configure

Drop a .factory-check.json in the repo to disable a rule:

{ "disabledRules": ["update-delete-no-where"] }

The report prints how many rules are disabled. If you find yourself disabling more than a handful, the rule design is wrong — open an issue, don't paper over it.

From source

npm install && npm run build   # builds dist/ via tsup
npm test                       # vitest, with a coverage floor
node bin/factory-kit-check.js .

What's in here

Skills (factory-*.md)

Synthesized cross-build conventions. Auto-loaded by Claude Code from ~/.claude/skills/.

Skill	Domain
factory-voice	Architect voice, first-principles framing, structured shape for Linear / PR / commit prose (loaded every session)
factory-stack	Locked + flexible stack decisions, decision criteria
factory-frontend	DataTable + drawer-CRUD, RowActions, formatters, Mantine vs shadcn
factory-design	Semantic token vocabulary, CSS-var + Tailwind bridge, dark/light as variable swap, primitives as token consumers, vocabulary-sprawl failure mode
factory-auth	Better Auth + orgs primary, RLS/Clerk criteria, wrapper interface
factory-data-layer	Drizzle schema partitioning, multi-tenancy keys, timestamps helper
factory-db-migration	Destructive prod-write runbook: preflight/mutate/verify/rollback, idempotency by natural key, Layer C backup independence, human-gated execution
factory-forms	react-hook-form + Zod variants, field registry, masked inputs
factory-api	Server actions vs tRPC criteria; validation; error shape
factory-data-pipelines	CSV imports, time-series envelopes, Python service entry points
factory-testing	Vitest + Playwright, __tests__ co-location, provider wrappers, mock factories, coverage thresholds
factory-llm-workflows	LangGraph TypedDict state, node factories, RAG, SSE streaming
factory-prompting	XML-tag prompt vocabulary, minimum-tagging discipline, tag-sprawl failure mode. Paired with /prompt
factory-security	KMS-at-rest, BAA/PHI, safe redirects, AI-code risk
factory-observability	PostHog + Sentry day 1, activity logging, trace IDs
factory-deployment	Vercel + Cloud Run + Terraform conventions
factory-ci	Single ci.yml merge gate, ephemeral PR DB, coverage floor, Claude Code reviewer as required check
factory-commits	Conventional Commits + required Linear-ID; commitlint config
factory-pitfalls	Flat cross-skill index of Failure mode blocks + process-level pitfalls without a skill home

Agents (specialist subagents)

Each is a Claude Code subagent file (YAML frontmatter + markdown body). Callable via the Agent tool.

Agent	When to invoke
feature-architect	Scope a vague client ask into a buildable feature spec; routes to the right specialists
frontend-engineer	UI scaffolding, CRUD surfaces, component-library decisions
db-schema-architect	Drizzle schemas, migrations, multi-tenancy keys
db-migration-engineer	Destructive prod-write runbook discipline; sister to db-schema-architect — owns preflight/mutate/verify/rollback, idempotency proof, Layer C snapshot gating
auth-wiring-specialist	Auth provider setup, RBAC, org context
forms-builder	Multi-step forms, field registry, conditional visibility
api-route-engineer	Endpoints, validation, error responses, pagination
data-pipeline-engineer	CSV ingestion, Python services, simulation envelopes
llm-workflow-engineer	LangGraph workflows, RAG, structured output, streaming
security-engineer	Threat-model a feature, audit AI-generated code, sensitive-data handling
code-reviewer	PR review against factory-pitfalls.md checklist

Slash commands

Linear ticket workflow — project-agnostic. Each project that wants these runs /setup-linear once to create .claude/linear.json.

• /setup-linear — bootstrap .claude/linear.json (team, optional project, state names)
• /standup — in-progress / in-review / top priority / backlog view
• /entry <issue> — load a Linear issue into context and enter plan mode
• /submit [issue] — move ticket to "In Review" (auto-detects from branch)
• /close [issue] — closing comment + Done + delete local branch / exit worktree
• /release patch|minor|major — bump VERSION, commit, tag with auto-generated notes (edited in Cursor), push after confirmation

Branch convention: any branch containing <teamkey>-<num> parses out (e.g. nishu/non-45-topic → NON-45).

Prompt authoring — no project config needed.

• /prompt <rough ask> — convert a messy one-liner into a structured XML-tagged prompt using the factory-prompting.md vocabulary

Kit diagnostics — no project config needed.

• /kit-audit — measure the kit's token footprint (baseline vs on-demand, heaviest assets, trim candidates)

User-level CLAUDE.md

CLAUDE.md in this repo is symlinked to ~/.claude/CLAUDE.md and listed by Claude Code on every project. Per-project decisions still live in each project's own CLAUDE.md or DECISIONS.md.

Versioning

SemVer, with a long 0.x runway:

• 0.x.0 — new skill/agent/command, or behavior change downstream projects could feel
• 0.x.y — content edits inside existing files, doc tweaks, install.sh fixes
• 1.0.0 — when renames stop and the kit feels stable enough to depend on

The "API surface" is skill filenames + frontmatter, agent filenames + subagent_type names, slash command names, and install.sh behavior. Symlink installs track HEAD by default; git checkout v0.x.y before re-running install.sh to pin a release.

Building in public

• Releases — the changelog
• Discussions — design questions in the open
• Twitter/X: @nishu_lahoti — short threads per minor tag

License

MIT — see LICENSE.