ForgeKit

Curated Claude Code project configs — a development constitution, slash commands, reference docs, and stack-specific patterns. Adds real .claude/commands/ and .claude/docs/ files directly into your project repo so they're committed and shared with collaborators.

Quick Start

cd your-project
npx forgekit init

ForgeKit auto-detects your stack from package.json and pre-selects the right patterns:

Auto-detected: Next.js, React, TypeScript (from package.json)

Which stack patterns should Claude reference? (toggle number, Enter to confirm)

  [x] 1. TypeScript   — ServiceResult, Zustand, hooks, types
  [x] 2. React        — Component structure, memoization, hook rules
  [x] 3. Next.js      — App Router, server/client components, Supabase
  [ ] 4. Expo         — React Native, theme, offline-first, performance
  [ ] 5. Backend      — API routes, middleware, database, auth patterns
  [x] 6. Performance  — Bundle analysis, rendering, profiling, mobile optimization
  [ ] 7. Forms        — react-hook-form, Zod validation, form state, async validation
  [ ] 8. Animation    — Reanimated 3, gesture handling, layout animations, springs
  [x] 9. Routing      — Expo Router, Next.js App Router, deep links, auth guards

Or skip the prompt entirely:

npx forgekit init --yes                         # auto-detect, no prompts
npx forgekit init -y -p typescript,nextjs       # specific patterns, no prompts

What It Creates

your-project/
├── .claude/
│   ├── commands/
│   │   ├── scaffold-feature.md    ← /scaffold-feature [desc]
│   │   ├── review.md              ← /review [target]
│   │   ├── fix-bug.md             ← /fix-bug [desc]
│   │   ├── refactor.md            ← /refactor [target]
│   │   ├── status.md              ← /status
│   │   └── plan.md                ← /plan [decision]
│   ├── docs/
│   │   ├── architect.md           ← Architecture planning + bounded contexts
│   │   ├── code-reviewer.md       ← Code review checklist with why-annotations
│   │   ├── ui-auditor.md          ← UI review checklist
│   │   ├── test-writer.md         ← Testing process
│   │   ├── doc-keeper.md          ← Documentation update process
│   │   ├── security-reviewer.md   ← Security review checklist
│   │   ├── env-config.md          ← Environment config pattern
│   │   ├── logger-template.md     ← Logger service template
│   │   ├── decisions.md           ← Decision trees for state, components, services
│   │   ├── anti-patterns.md       ← 13 anti-patterns with fixes and smell tests
│   │   ├── a11y.md                ← Accessibility patterns (React Native + Web)
│   │   ├── testing-strategy.md    ← Testing philosophy, diamond, mock vs real
│   │   ├── typescript-patterns.md ← (if selected)
│   │   ├── react-patterns.md      ← (if selected)
│   │   ├── nextjs-patterns.md     ← (if selected)
│   │   ├── expo-patterns.md       ← (if selected)
│   │   ├── backend-patterns.md    ← (if selected)
│   │   ├── performance-patterns.md← (if selected)
│   │   ├── forms-patterns.md      ← (if selected)
│   │   ├── animation-patterns.md  ← (if selected)
│   │   └── routing-patterns.md    ← (if selected)
│   └── .forgekit-manifest.json    ← Tracks installed files + content hashes
└── CLAUDE.md                      ← Development constitution

Commands

init

npx forgekit init
npx forgekit init --yes                    # auto-detect, skip prompts
npx forgekit init -y -p typescript,react   # explicit patterns, skip prompts

Adds ForgeKit configs to the current directory. If already installed, asks to re-initialize (removes old files first, then installs fresh).

update

npx forgekit update
npx forgekit update --yes    # no confirmation prompt

Updates ForgeKit configs to the latest templates without overwriting your edits. Uses SHA-256 content hashes to distinguish your changes from template changes:

• Files you haven't touched → replaced with new template
• Files you've customized → left alone
• New files in the current version → added

ForgeKit update: v3.0.0 → v4.0.0

New files (will be added):
  .claude/docs/decisions.md
  .claude/docs/anti-patterns.md
  .claude/docs/a11y.md
  .claude/docs/testing-strategy.md

Updated files (no local changes — will be replaced):
  .claude/docs/architect.md
  .claude/docs/code-reviewer.md

Locally modified (will be SKIPPED to preserve your changes):
  CLAUDE.md

Proceed? (y/N)

remove

npx forgekit remove

Removes all ForgeKit-installed files, cleans the CLAUDE.md marker block, and removes empty directories. Safe to run multiple times.

CLI Flags

| Flag | Short | Effect | |------|-------|--------| | --version | -v | Print version and exit | | --help | -h | Print usage and exit | | --yes | -y | Skip all prompts (uses auto-detected or --patterns) | | --patterns <ids> | -p | Comma-separated pattern IDs (init only) |

npx forgekit --version
npx forgekit --help
npx forgekit init --yes
npx forgekit init -y -p typescript,nextjs

What's Inside

Constitution (CLAUDE.md)

Core engineering rules injected into your project's CLAUDE.md between markers. Covers quality-first philosophy, project analysis protocol, phased execution, code quality standards, error handling, security, environment configuration, testing, documentation, and git conventions.

Commands (6 slash commands)

Real .claude/commands/ files that work as Claude Code slash commands:

| Command | Purpose | |---------|---------| | /scaffold-feature [desc] | Plan and build a feature with phased execution | | /review [target] | Full quality review using multiple checklists (code, security, UI, tests) | | /fix-bug [desc] | Structured bug diagnosis and fix | | /refactor [target] | Plan-first refactoring with approval gates | | /status | Quick project health check | | /plan [decision] | Think through a technical decision before building |

Reference Docs (12 core + optional patterns)

Placed in .claude/docs/ where the constitution and commands reference them:

| Document | Purpose | |----------|---------| | architect.md | Architecture planning, bounded contexts, over-engineering, data flow | | code-reviewer.md | Code review checklist with "why this matters" for every item | | ui-auditor.md | UI review checklist | | test-writer.md | Testing process | | doc-keeper.md | Documentation update process | | security-reviewer.md | Security review checklist | | env-config.md | Zod-validated environment config pattern | | logger-template.md | Copy-paste-ready Logger service template | | decisions.md | Decision trees for state placement, component vs hook, service vs extend | | anti-patterns.md | 13 anti-patterns with code examples, why-it-hurts, and the fix | | a11y.md | Accessibility patterns for React Native and Web | | testing-strategy.md | Testing philosophy, testing diamond, mock vs real decisions |

Stack Patterns (9 optional)

Auto-detected from package.json during init, or specified with --patterns:

| Pattern | Auto-detects | Covers | |---------|-------------|--------| | TypeScript | typescript | ServiceResult, discriminated unions, branded types, type narrowing | | React | react, react-dom | Compound components, controlled/uncontrolled, slot pattern, API design | | Next.js | next | App Router, server/client components, Supabase SSR, Tailwind/shadcn | | Expo | expo, react-native | React Native components, theme system, offline-first, i18n | | Backend | express, fastify, hono, koa, @nestjs/core, hapi | API routes, middleware, repository pattern, auth, database, testing | | Performance | react, react-native, next | Re-render optimization, bundle analysis, list virtualization, profiling | | Forms | react-hook-form, @hookform/resolvers | react-hook-form + Zod, form state machine, async validation, testing | | Animation | react-native-reanimated, framer-motion | Reanimated 3, springs vs timing, gestures, layout animations | | Routing | expo-router, next | Expo Router, Next.js App Router, deep linking, auth guards |

Updating

When a new version of ForgeKit ships, run:

npx forgekit update

ForgeKit stores a SHA-256 hash of each file at install time in the manifest. During update, it compares the current file hash against the stored baseline:

• Hash matches → you didn't edit it → safe to replace with new template
• Hash differs → you edited it → skipped, your changes are preserved

Files you've customized are never overwritten by update. To replace a customized file intentionally, delete it and re-run update, or re-run init.

Customization

After init, all files belong to your project. Edit them freely:

• CLAUDE.md — adjust rules to match your team's conventions
• Commands — modify workflows or add new ones in .claude/commands/
• Docs — update checklists, add project-specific sections
• Patterns — tailor code examples to your actual codebase

License

MIT