Skip to content
groundworkDocs

Set up a project

Start a new project with the whole kit, or add the design system to one you already have.

The whole kit

From an empty folder to a first feature. Run these once, in order.

  1. 1

    Create the app

    A Next.js app with TypeScript, Tailwind, ESLint and the App Router. kit init edits the files this creates, so pass the flags rather than relying on saved preferences.

    bunx create-next-app@latest your-app --ts --tailwind --eslint --app --use-bun --yes

    Want the app at the root of an existing repo?

    create-next-app checks that the target's parent is writable, so create-next-app . can fail in a sandbox whose writable root is the repo itself. Scaffold into a subfolder and move its contents up, .gitignore included.

    Running inside a sandboxed agent?

    bunx writes to the system temp and cache directories first; under a file sandbox that fails with EPERM before anything runs. Point them at a writable place first: TMPDIR=/tmp BUN_INSTALL_CACHE_DIR=/tmp/bun-cache. A first ConnectionRefused downloading package manifest that works on an identical retry is the download, not your registry configuration — run it again.
  2. 2

    Run kit init

    Copies the house style into context/, installs the skills, runs shadcn init against the registry, removes the leftover CSS that would override the theme, wires the lint rule, adds a check script, and locks what it installed.

    cd your-app && bunx @ja3dan/kit init next16-insforge
    your-app/
    • .claude/skills/
    • app/globals.css
    • context/
      • features/
        • README.md
      • code-standards.md
      • library-docs.md
      • progress.md
      • ui-registry.md
      • ui-rules.md
    • components.json
    • eslint.config.mjs
    • kit.lock.json
    • package.json
    Use the arrow keys to move. Right expands a folder, left collapses it or climbs to its parent. Home and End jump to the ends, and typing a letter jumps to the next name starting with it.

    Before the first check: generate route types

    Next generates LayoutProps and PageProps into .next/types. create-next-app does it during install — not with --skip-install — and moving routes into groups later leaves stale paths behind. Either way bun run check fails on types that aren't yours; rm -rf .next/types && bunx next typegen regenerates them.

    Linking a backend before your first commit?

    Some CLIs append a bare .claude to .gitignore (the InsForge CLI does), which hides the skills kit init just installed from git. kit doctor flags it; narrow the rule to .claude/settings.local.json.
  3. 3

    Write the context

    Paste the kickoff prompts into any LLM chat, in order, and save each answer into context/. Each answer is the next prompt's input.

    your-app/
    • context/
      • project-overview.md
      • architecture.md
      • build-plan.md
    Use the arrow keys to move. Right expands a folder, left collapses it or climbs to its parent. Home and End jump to the ends, and typing a letter jumps to the next name starting with it.
    Read the prompts
  4. 4

    Check the project

    kit doctor and kit check pass straight away. bun run check fails on create-next-app's own home page, which uses raw palette colours: that is the lint rule working, and it passes once the first feature replaces the page.

    bunx @ja3dan/kit doctor
    required files, kickoff docs, git-ignored kit files, and outdated/missing items
    bunx @ja3dan/kit check
    scan locked files for raw colours and a theme missing required tokens
    bunx @ja3dan/kit list
    every item the registry can install, and which are installed here
    bun run check
    typecheck and lint, including no-raw-colors
  5. 5

    Start the first feature

    In Claude Code, from the project. The feature skill opens a branch and a folder, and writes the spec with its done when criteria.

    /feature start 01
    Read the loop

Only the design system

shadcn does the install. Two things kit init would have done are yours to do by hand.

Before you start, in an app with its own styles

Search the codebase for the contract's token names (primary, accent, success and the rest). A name the app already uses for something else takes on the contract's meaning once the theme loads. Override it straight after the imports.
  1. 1

    Initialise on the contract

    Initialises a project on the token contract: installs @ja3dan/tokens and the lint plugin, wires the theme into global CSS, adds the @ja3dan registry to components.json. Run with shadcn init.

    bunx shadcn@latest init https://gw.jaedan.me/r/setup.json
  2. 2

    Remove the leftover CSS

    In a fresh create-next-app project, app/globals.css keeps its own colour variables, a dark media query copy and a body rule after the imports, and they override the theme. Keep the imports below and any --font-* lines; delete the rest.

    app/globals.css
    @import "tw-animate-css";@import "@ja3dan/tokens/theme.css";@import "@ja3dan/tokens/base.css";@import "@ja3dan/tokens/themes/neutral.css";
  3. 3

    Wire the lint rule

    The plugin is installed but does not run until the config names it. Add these two lines to eslint.config.mjs.

    eslint.config.mjs
    import ja3dan from "@ja3dan/eslint-plugin";// inside the config array:{ ...ja3dan.configs.recommended, files: ["app/**/*.{ts,tsx}", "components/**/*.{ts,tsx}"] },
  4. 4

    Add components

    Start with the button, which replaces shadcn's, then add any of the other 23.

    bunx shadcn@latest add @ja3dan/button --overwrite
    Browse the components

Keep it current

Installed components and skills are yours to edit. The kit tells you when a newer version exists, merges components with your edits, and leaves an edited skill alone unless you say otherwise.

bunx @ja3dan/kit sync status
what's outdated, and what's been edited locally
bunx @ja3dan/kit sync update <item>
update one item on a branch: overwrite if unedited, 3-way merge if edited
bunx @ja3dan/kit@latest skills status
the project's skills against this kit's: current, outdated, edited, missing, new
bunx @ja3dan/kit@latest skills update
install this kit's skills over outdated, missing and new ones, and lock them

Where to go next