Factory Kit

Factory Kit is a portable software-factory playbook for Claude and Codex. One canonical Open Agent Skills tree contains the knowledge, ticket workflows, and specialist workflows. Claude commands and subagents are thin compatibility adapters over that tree.

The kit separates stack-independent principles from the opinionated Factory recipe: Next.js, Drizzle, Better Auth, Mantine or shadcn, Cloud Run, Linear, and the operational failure modes learned across production builds.

Install

Choose either the universal npm bootstrap or a native plugin marketplace. They are alternative installation methods, not prerequisites for each other.

Universal npm bootstrap

npx @nonlinear-labs/factory-kit install --target auto

auto detects whether Claude or Codex invoked the installer. If both or neither host can be identified, the command fails with an explicit --target claude|codex|all choice instead of guessing.

factory-kit install --target claude
factory-kit install --target codex
factory-kit install --target all
factory-kit install --target auto --global-guidance
factory-kit install --target auto --skip-linear

Running npx @nonlinear-labs/factory-kit without arguments retains the original Claude-only bootstrap target. Global guidance is still opt-in.

The bootstrap installs directory symlinks for canonical skills. Claude also receives the existing command and subagent names. Re-running is idempotent. Factory Kit-owned legacy flat links are migrated; user-owned files and unrelated symlinks are preserved as conflicts.

From a local clone:

./install.sh

Claude plugin marketplace

claude plugin marketplace add nonlinear-xyz/factory-kit
claude plugin install factory-kit@factory-kit

Codex plugin marketplace

codex plugin marketplace add nonlinear-xyz/factory-kit
codex plugin add factory-kit@factory-kit

The repository contains both catalogs and both manifests over the same root skills/ tree. Native installs bundle the official Linear HTTP MCP endpoint; the host requests authorization.

Pasteable agent prompt

Install Factory Kit with npx @nonlinear-labs/factory-kit install --target auto. Preserve all existing global instructions and user-owned files. Leave global guidance disabled unless I explicitly request it. If host detection is ambiguous, stop and tell me to choose Claude or Codex.

Global guidance

Factory Kit never replaces a global instruction file. Guidance is installed only through a marked, reversible block assembled from shared content plus a host adapter.

factory-kit guidance add --target claude
factory-kit guidance add --target codex
factory-kit guidance add --target all

factory-kit guidance remove --target claude
factory-kit guidance remove --target codex
factory-kit guidance remove --target all

The managed block lives in ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md. Updates replace only that block. Removal preserves the surrounding file byte-for-byte.

Linear workflows

Project configuration belongs at .factory-kit/linear.json:

{
  "teamKey": "NON",
  "teamId": "<uuid>",
  "projectId": "<optional-uuid>",
  "projectName": "<optional-name>",
  "states": {
    "inReview": "In Review",
    "done": "Done"
  },
  "branchPattern": "<owner>/<team-key>-<number>-<topic>"
}

.claude/linear.json remains a read-only migration fallback. The setup-linear workflow writes the canonical path. The npm bootstrap registers Linear by default without storing credentials; --skip-linear leaves host MCP configuration untouched.

Diagnostics

factory-kit doctor --target claude
factory-kit doctor --target codex
factory-kit doctor --target all

doctor reports canonical skill links, native plugin detection, managed guidance, stale flat links, and the duplicate-skill risk when native and symlink installs coexist.

Architecture

factory-kit/
├── skills/<factory-name>/SKILL.md   # canonical knowledge and workflows
├── commands/*.md                    # thin Claude slash-command adapters
├── agents/*.md                      # thin Claude agents with skill preloads
├── guidance/
│   ├── shared.md
│   ├── claude.md
│   └── codex.md
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── .codex-plugin/plugin.json
├── .agents/plugins/marketplace.json
├── .mcp.json                        # official Linear HTTP MCP
├── bin/factory-kit.js               # universal installer and doctor
├── check/                            # deterministic conformance engine
└── templates/factory-conformance.yml

There are 41 canonical skills:

  • 21 principle-first knowledge skills: voice, stack, frontend, design, animation, auth, data layer, database migration, forms, API, data pipelines, testing, LLM workflows, prompting, security, observability, deployment, CI, commits, pitfalls, and verification.
  • 8 portable command workflows: standup, entry, submit, close, release, setup-linear, prompt, and kit-audit.
  • 12 portable specialist workflows: feature architect, frontend engineer, database schema architect, database migration engineer, auth wiring specialist, forms builder, API route engineer, data pipeline engineer, LLM workflow engineer, security engineer, code reviewer, and verification engineer.

The canonical folder name and the name in each skill's YAML frontmatter are the same public identifier.

Knowledge skills

Skill Domain
factory-animation Motion discipline, attention budgets, diegetic motion, and reduced-motion fallbacks
factory-api Server actions and tRPC conventions, validation, pagination, errors, and audit logging
factory-auth Auth-provider decisions, authorization wrappers, session handling, and callback safety
factory-ci Merge-gate structure, required checks, automated review, and deploy separation
factory-commits Conventional Commits, Linear references, commitlint, and branch conventions
factory-data-layer Drizzle schemas, multi-tenancy, shared helpers, JSONB, and migration boundaries
factory-data-pipelines CSV ingestion, time-series envelopes, Python services, and simulation pipelines
factory-db-migration Production database runbooks: preflight, mutation, verification, rollback, and idempotency
factory-deployment Vercel, Cloud Run, Neon, Terraform, environment handling, and migration execution
factory-design Semantic tokens, theme variables, primitives, and design-vocabulary discipline
factory-forms react-hook-form, Zod variants, field registries, conditional fields, and uploads
factory-frontend CRUD surfaces, tables, drawers, row actions, formatting, and component-library choices
factory-llm-workflows LangGraph state, node factories, RAG, structured output, and SSE streaming
factory-observability PostHog, Sentry, trace IDs, structured logs, audit events, and PII boundaries
factory-pitfalls Cross-skill index of observed implementation and process failure modes
factory-prompting XML-tag prompt vocabulary, minimum-tagging discipline, and prompt structure
factory-security Sensitive-data handling, KMS, safe redirects, rate limiting, and AI-code safeguards
factory-stack Locked stack choices, flexible seams, and criteria for context-driven decisions
factory-testing Vitest, Playwright, co-location, shared test utilities, and coverage thresholds
factory-verification Verification tiers, eval graduation, coverage disclosure, and delta-gated conformance
factory-voice First-principles architectural communication for sessions, Linear, commits, and PRs

Portable command-workflow skills

Skill Claude adapter Workflow
factory-close /close Complete a Linear issue, leave a closing comment, and clean up the branch or worktree
factory-entry /entry Load a Linear issue into context and enter a focused planning session
factory-kit-audit /kit-audit Measure baseline and on-demand token footprint and identify heavy assets
factory-prompt /prompt Turn a rough ask into a structured prompt using the prompting vocabulary
factory-release /release Synchronize versions, prepare notes, and run gated release and publication steps
factory-setup-linear /setup-linear Configure portable Linear settings with legacy migration support
factory-standup /standup Group open Linear work into in-flight, priority, and backlog views
factory-submit /submit Move the branch-associated Linear issue to In Review

Portable specialist-workflow skills

Skill Claude agent adapter Workflow
factory-api-route-engineer api-route-engineer Design endpoints using the factory's API, validation, pagination, and error conventions
factory-auth-wiring-specialist auth-wiring-specialist Wire providers, roles, organizations, callbacks, and unified auth wrappers
factory-code-reviewer code-reviewer Review a diff against factory conventions and the pitfalls checklist
factory-data-pipeline-engineer data-pipeline-engineer Build ingestion, time-series, simulation, and adjacent Python-service workflows
factory-db-migration-engineer db-migration-engineer Produce human-gated production mutation runbooks and verification criteria
factory-db-schema-architect db-schema-architect Design Drizzle schemas, migrations, tenancy keys, and polymorphic data models
factory-feature-architect feature-architect Turn a vague request into a scoped feature specification and specialist routing plan
factory-forms-builder forms-builder Build complex forms with schema variants, field registries, and conditional behavior
factory-frontend-engineer frontend-engineer Build house-style lists, forms, tables, drawers, and entity-editing surfaces
factory-llm-workflow-engineer llm-workflow-engineer Build stateful LLM, RAG, structured-output, and streaming workflows
factory-security-engineer security-engineer Threat-model features and produce concrete sensitive-data and authorization fixes
factory-verification-engineer verification-engineer Design blast-radius-aware verification strategies and identify proof gaps

Claude compatibility adapters

Claude preserves the existing command and subagent names with thin adapters. Agent routing descriptions, tool permissions, models, and canonical skill preloads remain part of the compatibility surface.

Agents

Agent Model Preloaded skill When to invoke
feature-architect Sonnet factory-feature-architect Scope a vague client ask into a buildable feature specification
frontend-engineer Sonnet factory-frontend-engineer Scaffold lists, forms, drawers, tables, and entity-editing surfaces
db-schema-architect Sonnet factory-db-schema-architect Design schemas, migrations, tenancy keys, and polymorphic structures
db-migration-engineer Sonnet factory-db-migration-engineer Plan destructive production data changes with gated runbook discipline
auth-wiring-specialist Sonnet factory-auth-wiring-specialist Wire auth providers, RBAC, organizations, callbacks, and wrapper seams
forms-builder Sonnet factory-forms-builder Build multi-step, conditional, auto-saving, or upload-heavy forms
api-route-engineer Sonnet factory-api-route-engineer Design server actions, tRPC procedures, or external REST routes
data-pipeline-engineer Sonnet factory-data-pipeline-engineer Build ingestion, time-series, simulation, or Python-service pipelines
llm-workflow-engineer Sonnet factory-llm-workflow-engineer Build LangGraph, RAG, structured-output, or streaming LLM workflows
security-engineer Sonnet factory-security-engineer Threat-model a feature or audit sensitive and AI-generated code paths
code-reviewer Sonnet factory-code-reviewer Review a PR or diff against the factory's conventions; read-only
verification-engineer Sonnet factory-verification-engineer Design a verification plan and surface unverifiable gaps; read-only

Slash commands

  • /standup — show open Linear tickets grouped by in-flight, top priority, and backlog
  • /entry <issue> — load a Linear issue into context and enter a focused planning session
  • /submit [issue] — move a Linear issue to In Review, auto-detecting it from the branch when omitted
  • /close [issue] — leave a closing comment, move the issue to Done, and clean up the branch or worktree
  • /release [patch|minor|major] — run the gated version, notes, tag, GitHub Release, and npm publication workflow
  • /setup-linear — configure .factory-kit/linear.json, using legacy Claude configuration as migration input
  • /prompt <rough ask> — convert a rough ask into a structured XML-tagged prompt
  • /kit-audit — measure baseline and on-demand token footprint and identify trim candidates

factory-kit-check

Skills describe the conventions. factory-kit-check enforces a deterministic subset:

factory-kit-check
factory-kit-check ../some-repo
factory-kit-check . --base origin/main --md
npx @nonlinear-labs/factory-kit add-ci

The checker is read-only. Without --base, critical and high findings produce a non-zero exit. With --base, the conformance gate evaluates the delta and blocks newly introduced critical findings by default.

Rule Severity Citation
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

Configure repository-specific exclusions in .factory-check.json:

{
  "disabledRules": ["update-delete-no-where"],
  "ignorePaths": ["**/__tests__/**"],
  "gateOnHigh": false
}

Development

npm install
npm test
npm run build
npm pack --dry-run
node bin/factory-kit-check.js .
claude plugin validate --strict .claude-plugin/plugin.json
claude plugin validate --strict .claude-plugin/marketplace.json

The test suite exercises temporary-home installs for Claude, Codex, both targets, auto detection, idempotency, legacy migration, conflicts, Linear configuration, managed guidance, duplicate-install diagnostics, skill frontmatter, references, and plugin metadata.

Versioning

SemVer uses a long 0.x runway. Version 0.4.0 introduces the portable canonical skill tree and cross-host installation surfaces. Skill names, Claude command names, Claude agent names/frontmatter, installer commands, and checker citations are compatibility API.

No package publication, tag, push, or release is performed by repository validation.

License

MIT — see LICENSE.