create-skaff 0.0.5 → 0.0.7

package/bin/skaff.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/index.tsx";

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "create-skaff",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Interactive Next.js project scaffolder: Tailwind, shadcn/ui, Motion, Lucide, Oxlint, Oxfmt, Ultracite, Claude and Codex config",
   "type": "module",
   "bin": {
-    "create-skaff": "./src/index.tsx",
-    "skaff": "./src/index.tsx"
+    "create-skaff": "bin/skaff.js",
+    "skaff": "bin/skaff.js"
   },
   "files": [
+    "bin",
     "src"
   ],
   "scripts": {

package/src/components/progress-timeline.tsx

@@ -14,9 +14,11 @@ export function ProgressTimeline({ config, onExit }: ProgressTimelineProps) {
   });
   return (
     <box flexDirection="column">
-      {steps.map((step) => (
-        <StepRow key={step.id} step={step} />
-      ))}
+      {steps
+        .filter((step) => step.status !== "pending")
+        .map((step) => (
+          <StepRow key={step.id} step={step} />
+        ))}
       {error ? (
         <box flexDirection="column">
           <text>

package/src/components/radio-prompt.tsx

@@ -0,0 +1,50 @@
+import { useKeyboard } from "@opentui/react";
+import { useState } from "react";
+
+export type RadioOption<T extends string> = { value: T; label: string; description?: string };
+
+type RadioPromptProps<T extends string> = {
+  title: string;
+  options: RadioOption<T>[];
+  initialValue: T;
+  onSelect: (value: T) => void;
+};
+
+export function RadioPrompt<T extends string>({ title, options, initialValue, onSelect }: RadioPromptProps<T>) {
+  const [index, setIndex] = useState(
+    Math.max(
+      0,
+      options.findIndex((option) => option.value === initialValue),
+    ),
+  );
+
+  useKeyboard((key) => {
+    if (key.name === "up" || key.name === "k") {
+      setIndex((current) => (current + options.length - 1) % options.length);
+    } else if (key.name === "down" || key.name === "j") {
+      setIndex((current) => (current + 1) % options.length);
+    } else if (key.name === "return") {
+      onSelect(options[index].value);
+    }
+  });
+
+  return (
+    <box flexDirection="column">
+      <text>
+        <span fg="#a78bfa">◆</span>  <strong>{title}</strong>
+      </text>
+      {options.map((option, i) => (
+        <text key={option.value}>
+          <span fg="#a78bfa">│  </span>
+          {i === index ? <span fg="#4ade80">◉ </span> : <span fg="#555555">○ </span>}
+          <span fg={i === index ? "#ffffff" : "#888888"}>{option.label}</span>
+          {option.description ? <span fg="#666666">{`  ${option.description}`}</span> : null}
+        </text>
+      ))}
+      <text>
+        <span fg="#a78bfa">│  </span>
+        <span fg="#666666">↑↓ to move · Enter to continue · Esc to go back</span>
+      </text>
+    </box>
+  );
+}

package/src/components/wizard-app.tsx

@@ -1,16 +1,17 @@
 import { useKeyboard, useRenderer } from "@opentui/react";
 import { useState } from "react";
 import { allFeatureIds, allFeatures, type FeatureId } from "../lib/features";
-import type { PackageManager } from "../lib/package-manager";
+import { type PackageManager, packageManagers } from "../lib/package-manager";
+import { type ShadcnPreset, shadcnPresets } from "../lib/shadcn-presets";
 import type { ScaffoldConfig } from "../lib/scaffold-steps";
 import { AnsweredRow } from "./answered-row";
 import { ConfirmPrompt } from "./confirm-prompt";
 import { FeaturesPrompt } from "./features-prompt";
 import { NamePrompt } from "./name-prompt";
-import { PackageManagerPrompt } from "./package-manager-prompt";
 import { ProgressTimeline } from "./progress-timeline";
+import { RadioPrompt } from "./radio-prompt";
 
-const screens = ["name", "packageManager", "features", "confirm", "progress"] as const;
+const screens = ["name", "packageManager", "features", "shadcnPreset", "confirm", "progress"] as const;
 
 type Screen = (typeof screens)[number];
 
@@ -22,6 +23,7 @@ export function WizardApp({ initialName, cwd, dryRun }: WizardAppProps) {
   const [name, setName] = useState(initialName);
   const [packageManager, setPackageManager] = useState<PackageManager>("pnpm");
   const [features, setFeatures] = useState<FeatureId[]>(allFeatureIds);
+  const [shadcnPreset, setShadcnPreset] = useState<ShadcnPreset>("nova");
   const [config, setConfig] = useState<ScaffoldConfig | null>(null);
 
   const exit = () => {
@@ -32,17 +34,21 @@ export function WizardApp({ initialName, cwd, dryRun }: WizardAppProps) {
   const step = screens.indexOf(screen);
   const answered = (target: Screen) => step > screens.indexOf(target);
 
+  const usesShadcn = features.includes("shadcn");
+
   useKeyboard((key) => {
     if (key.name === "escape") {
       if (screen === "name") {
         exit();
+      } else if (screen === "confirm" && !usesShadcn) {
+        setScreen("features");
       } else if (screen !== "progress") {
         setScreen(screens[step - 1]);
       }
       return;
     }
     if (screen === "confirm" && key.name === "return") {
-      setConfig({ name, packageManager, cwd, features, dryRun });
+      setConfig({ name, packageManager, cwd, features, shadcnPreset, dryRun });
       setScreen("progress");
     }
   });
@@ -64,6 +70,7 @@ export function WizardApp({ initialName, cwd, dryRun }: WizardAppProps) {
       {answered("name") ? <AnsweredRow label="Project name" value={name} /> : null}
       {answered("packageManager") ? <AnsweredRow label="Package manager" value={packageManager} /> : null}
       {answered("features") ? <AnsweredRow label="What to set up" value={featureSummary} /> : null}
+      {answered("shadcnPreset") && usesShadcn ? <AnsweredRow label="shadcn/ui preset" value={shadcnPreset} /> : null}
       {screen === "name" ? (
         <NamePrompt
           initialValue={name}
@@ -74,7 +81,9 @@ export function WizardApp({ initialName, cwd, dryRun }: WizardAppProps) {
         />
       ) : null}
       {screen === "packageManager" ? (
-        <PackageManagerPrompt
+        <RadioPrompt
+          title="Package manager"
+          options={packageManagers.map((value) => ({ value, label: value }))}
           initialValue={packageManager}
           onSelect={(value) => {
             setPackageManager(value);
@@ -87,11 +96,22 @@ export function WizardApp({ initialName, cwd, dryRun }: WizardAppProps) {
           initialValue={features}
           onSubmit={(value) => {
             setFeatures(value);
+            setScreen(value.includes("shadcn") ? "shadcnPreset" : "confirm");
+          }}
+        />
+      ) : null}
+      {screen === "shadcnPreset" ? (
+        <RadioPrompt
+          title="shadcn/ui preset"
+          options={shadcnPresets}
+          initialValue={shadcnPreset}
+          onSelect={(value) => {
+            setShadcnPreset(value);
             setScreen("confirm");
           }}
         />
       ) : null}
-      {screen === "confirm" ? <ConfirmPrompt config={{ name, packageManager, cwd, features, dryRun }} /> : null}
+      {screen === "confirm" ? <ConfirmPrompt config={{ name, packageManager, cwd, features, shadcnPreset, dryRun }} /> : null}
       {screen === "progress" && config ? <ProgressTimeline config={config} onExit={exit} /> : null}
     </box>
   );

package/src/index.tsx

@@ -1,4 +1,3 @@
-#!/usr/bin/env bun
 import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { WizardApp } from "./components/wizard-app";

package/src/lib/features.ts

@@ -1,4 +1,17 @@
-export type FeatureId = "typography" | "shadcn" | "motion" | "lucide" | "ultracite" | "claude" | "codex";
+export type FeatureId =
+  | "typography"
+  | "shadcn"
+  | "motion"
+  | "lucide"
+  | "hugeicons"
+  | "tanstackQuery"
+  | "ultracite"
+  | "claude"
+  | "codex"
+  | "skillNextExperimental"
+  | "skillVercelComposition"
+  | "skillVercelReact"
+  | "skillShadcn";
 
 export type Feature = { id: FeatureId; label: string };
 
@@ -9,7 +22,7 @@ export const featureGroups: FeatureGroup[] = [
     title: "Styling",
     features: [
       { id: "typography", label: "Tailwind Typography" },
-      { id: "shadcn", label: "shadcn/ui (all components)" },
+      { id: "shadcn", label: "shadcn/ui (base, all components)" },
     ],
   },
   {
@@ -17,6 +30,8 @@ export const featureGroups: FeatureGroup[] = [
     features: [
       { id: "motion", label: "Motion (framer-motion)" },
       { id: "lucide", label: "Lucide icons" },
+      { id: "hugeicons", label: "Hugeicons (free)" },
+      { id: "tanstackQuery", label: "TanStack Query (provider + devtools)" },
     ],
   },
   {
@@ -30,6 +45,15 @@ export const featureGroups: FeatureGroup[] = [
       { id: "codex", label: "Codex config" },
     ],
   },
+  {
+    title: "AI skills (skills.sh)",
+    features: [
+      { id: "skillNextExperimental", label: "vercel-labs/next.js-experimental" },
+      { id: "skillVercelComposition", label: "vercel-composition-patterns" },
+      { id: "skillVercelReact", label: "vercel-react-best-practices" },
+      { id: "skillShadcn", label: "shadcn" },
+    ],
+  },
 ];
 
 export const allFeatures: Feature[] = featureGroups.flatMap((group) => group.features);

package/src/lib/scaffold-steps.ts

@@ -1,7 +1,10 @@
 import { join } from "node:path";
 import type { FeatureId } from "./features";
 import { type PackageManager, packageManagerCommands } from "./package-manager";
+import type { ShadcnPreset } from "./shadcn-presets";
+import { addQueryProvider } from "./utils/add-query-provider";
 import { addTypographyPlugin } from "./utils/add-typography-plugin";
+import { extendGitignore } from "./utils/extend-gitignore";
 import { type CommandResult, runCommand } from "./utils/run-command";
 import { writeAgentConfig } from "./utils/write-agent-config";
 
@@ -10,6 +13,7 @@ export type ScaffoldConfig = {
   packageManager: PackageManager;
   cwd: string;
   features: FeatureId[];
+  shadcnPreset: ShadcnPreset;
   dryRun: boolean;
 };
 
@@ -30,83 +34,119 @@ const command = (
   run: (config, onOutput) => runCommand(build(config), inProject ? projectDir(config) : config.cwd, onOutput),
 });
 
-const nextStep: ScaffoldStep = {
+const createNextApp = command(
+  ({ name, packageManager }) => [
+    ...packageManagerCommands[packageManager].dlx,
+    "create-next-app@latest",
+    name,
+    "--ts",
+    "--tailwind",
+    "--app",
+    "--no-src-dir",
+    "--import-alias",
+    "@/*",
+    "--yes",
+    packageManagerCommands[packageManager].createNextFlag,
+  ],
+  false,
+);
+
+const typographyInstall = command(({ packageManager }) => [
+  ...packageManagerCommands[packageManager].addDev,
+  "@tailwindcss/typography",
+]);
+
+const nextStep = (withTypography: boolean): ScaffoldStep => ({
   id: "next",
-  label: "Next.js + Tailwind (create-next-app)",
-  ...command(
-    ({ name, packageManager }) => [
-      ...packageManagerCommands[packageManager].dlx,
-      "create-next-app@latest",
-      name,
-      "--ts",
-      "--tailwind",
-      "--app",
-      "--no-src-dir",
-      "--import-alias",
-      "@/*",
-      "--yes",
-      packageManagerCommands[packageManager].createNextFlag,
-    ],
-    false,
-  ),
+  label: `Setting up Next.js + Tailwind${withTypography ? " + Typography" : ""}`,
+  describe: (config) =>
+    [
+      createNextApp.describe(config),
+      "extend .gitignore",
+      ...(withTypography ? [`${typographyInstall.describe(config)}, add @plugin to app/globals.css`] : []),
+    ].join(", then "),
+  run: async (config, onOutput) => {
+    onOutput("create-next-app");
+    const created = await createNextApp.run(config, onOutput);
+    if (!created.ok) {
+      return created;
+    }
+    await extendGitignore(projectDir(config));
+    if (!withTypography) {
+      return created;
+    }
+    onOutput("adding @tailwindcss/typography");
+    const typography = await typographyInstall.run(config, onOutput);
+    if (typography.ok) {
+      await addTypographyPlugin(projectDir(config));
+    }
+    return typography;
+  },
+});
+
+const shadcnInit = command(({ packageManager, shadcnPreset }) => [
+  ...packageManagerCommands[packageManager].dlx,
+  "shadcn@latest",
+  "init",
+  "-y",
+  "-b",
+  "base",
+  "-p",
+  shadcnPreset,
+  "--silent",
+]);
+
+const shadcnAddAll = command(({ packageManager }) => [
+  ...packageManagerCommands[packageManager].dlx,
+  "shadcn@latest",
+  "add",
+  "--all",
+  "-y",
+  "--silent",
+]);
+
+const shadcnStep: ScaffoldStep = {
+  id: "shadcn",
+  label: "Setting up shadcn/ui",
+  describe: (config) => `${shadcnInit.describe(config)}, then ${shadcnAddAll.describe(config)}`,
+  run: async (config, onOutput) => {
+    onOutput("init");
+    const init = await shadcnInit.run(config, onOutput);
+    if (!init.ok) {
+      return init;
+    }
+    onOutput("adding all components");
+    return shadcnAddAll.run(config, onOutput);
+  },
 };
 
-const typographyStep: ScaffoldStep = {
-  id: "typography",
-  label: "Tailwind Typography plugin",
+const tanstackQueryStep: ScaffoldStep = {
+  id: "tanstack-query",
+  label: "TanStack Query",
   describe: (config) =>
-    `$ ${[...packageManagerCommands[config.packageManager].addDev, "@tailwindcss/typography"].join(" ")}, then add @plugin to app/globals.css`,
+    `$ ${[...packageManagerCommands[config.packageManager].add, "@tanstack/react-query", "@tanstack/react-query-devtools"].join(" ")}, then write components/query-provider.tsx and wrap app/layout.tsx`,
   run: async (config, onOutput) => {
     const result = await runCommand(
-      [...packageManagerCommands[config.packageManager].addDev, "@tailwindcss/typography"],
+      [...packageManagerCommands[config.packageManager].add, "@tanstack/react-query", "@tanstack/react-query-devtools"],
       projectDir(config),
       onOutput,
     );
     if (result.ok) {
-      await addTypographyPlugin(projectDir(config));
+      await addQueryProvider(projectDir(config));
     }
     return result;
   },
 };
 
-const shadcnInitStep: ScaffoldStep = {
-  id: "shadcn-init",
-  label: "shadcn/ui init (radix, vega preset)",
-  ...command(({ packageManager }) => [
-    ...packageManagerCommands[packageManager].dlx,
-    "shadcn@latest",
-    "init",
-    "-y",
-    "-b",
-    "radix",
-    "-p",
-    "vega",
-    "--silent",
-  ]),
-};
-
-const shadcnAllStep: ScaffoldStep = {
-  id: "shadcn-all",
-  label: "shadcn/ui add --all",
-  ...command(({ packageManager }) => [
-    ...packageManagerCommands[packageManager].dlx,
-    "shadcn@latest",
-    "add",
-    "--all",
-    "-y",
-    "--silent",
-  ]),
-};
-
 const librariesStep = (packages: string[]): ScaffoldStep => ({
   id: "libraries",
   label: packages.join(" + "),
   ...command(({ packageManager }) => [...packageManagerCommands[packageManager].add, ...packages]),
 });
 
-const ultraciteStep = (agents: FeatureId[]): ScaffoldStep => ({
+const ultraciteStep = (withShadcn: boolean): ScaffoldStep => ({
   id: "ultracite",
-  label: agents.length > 0 ? `Ultracite (Oxlint, Oxfmt, ${agents.join(" + ")} config)` : "Ultracite (Oxlint, Oxfmt)",
+  label: `Ultracite (Oxlint${withShadcn ? " + shadcn rules" : ""}, Oxfmt)`,
   ...command(({ packageManager }) => [
     ...packageManagerCommands[packageManager].dlx,
     "ultracite@latest",
@@ -115,9 +155,9 @@ const ultraciteStep = (agents: FeatureId[]): ScaffoldStep => ({
     packageManager,
     "--linter",
     "oxlint",
-    ...(agents.length > 0 ? ["--agents", ...agents] : []),
     "--frameworks",
     "next",
+    ...(withShadcn ? ["shadcn", "--js-plugins", "@shadcn/lint"] : []),
     "--editors",
     "vscode",
     "--quiet",
@@ -127,22 +167,62 @@ const ultraciteStep = (agents: FeatureId[]): ScaffoldStep => ({
 const agentConfigStep = (agents: FeatureId[]): ScaffoldStep => ({
   id: "agents",
   label: `${agents.join(" + ")} config`,
-  describe: () => `write ${agents.map((agent) => (agent === "claude" ? "CLAUDE.md" : "AGENTS.md")).join(" and ")}`,
+  describe: () => `append project rules to AGENTS.md${agents.includes("claude") ? ", ensure CLAUDE.md points at it" : ""}`,
   run: async (config) => {
-    await writeAgentConfig(projectDir(config), agents);
+    await writeAgentConfig(projectDir(config), config);
     return { ok: true, output: "" };
   },
 });
 
+type SkillPackage = { id: string; repo: string; skills: string[] };
+
+const skillsStep = (pkg: SkillPackage, agents: string[]): ScaffoldStep => ({
+  id: `skills-${pkg.id}`,
+  label: `AI skills: ${pkg.repo}${pkg.skills[0] === "*" ? "" : ` (${pkg.skills.join(", ")})`}`,
+  ...command(({ packageManager }) => [
+    ...packageManagerCommands[packageManager].dlx,
+    "skills@latest",
+    "add",
+    pkg.repo,
+    "--skill",
+    ...pkg.skills,
+    "--agent",
+    ...agents,
+    "-y",
+  ]),
+});
+
+const skillPackages = (features: FeatureId[]): SkillPackage[] => {
+  const has = (id: FeatureId) => features.includes(id);
+  const vercel = [
+    ...(has("skillVercelComposition") ? ["vercel-composition-patterns"] : []),
+    ...(has("skillVercelReact") ? ["vercel-react-best-practices"] : []),
+  ];
+  return [
+    ...(has("skillNextExperimental")
+      ? [{ id: "next-experimental", repo: "vercel-labs/next.js-experimental", skills: ["*"] }]
+      : []),
+    ...(vercel.length > 0 ? [{ id: "vercel", repo: "vercel-labs/agent-skills", skills: vercel }] : []),
+    ...(has("skillShadcn") ? [{ id: "shadcn", repo: "shadcn-ui/ui", skills: ["shadcn"] }] : []),
+  ];
+};
+
 export function buildScaffoldSteps(features: FeatureId[]): ScaffoldStep[] {
   const has = (id: FeatureId) => features.includes(id);
-  const libraries = [...(has("motion") ? ["motion"] : []), ...(has("lucide") ? ["lucide-react"] : [])];
+  const libraries = [
+    ...(has("motion") ? ["motion"] : []),
+    ...(has("lucide") ? ["lucide-react"] : []),
+    ...(has("hugeicons") ? ["@hugeicons/react", "@hugeicons/core-free-icons"] : []),
+  ];
   const agents = features.filter((id): id is "claude" | "codex" => id === "claude" || id === "codex");
+  const skillAgents = agents.length > 0 ? agents.map((agent) => (agent === "claude" ? "claude-code" : "codex")) : ["claude-code", "codex"];
   return [
-    nextStep,
-    ...(has("typography") ? [typographyStep] : []),
-    ...(has("shadcn") ? [shadcnInitStep, shadcnAllStep] : []),
+    nextStep(has("typography")),
+    ...(has("shadcn") ? [shadcnStep] : []),
     ...(libraries.length > 0 ? [librariesStep(libraries)] : []),
-    ...(has("ultracite") ? [ultraciteStep(agents)] : agents.length > 0 ? [agentConfigStep(agents)] : []),
+    ...(has("tanstackQuery") ? [tanstackQueryStep] : []),
+    ...(has("ultracite") ? [ultraciteStep(has("shadcn"))] : []),
+    ...(agents.length > 0 ? [agentConfigStep(agents)] : []),
+    ...skillPackages(features).map((pkg) => skillsStep(pkg, skillAgents)),
   ];
 }

package/src/lib/shadcn-presets.ts

@@ -0,0 +1,12 @@
+export type ShadcnPreset = "nova" | "vega" | "maia" | "lyra" | "mira" | "luma" | "sera" | "rhea";
+
+export const shadcnPresets: { value: ShadcnPreset; label: string; description: string }[] = [
+  { value: "nova", label: "Nova", description: "Lucide / Geist" },
+  { value: "vega", label: "Vega", description: "Lucide / Inter" },
+  { value: "maia", label: "Maia", description: "Hugeicons / Figtree" },
+  { value: "lyra", label: "Lyra", description: "Phosphor / JetBrains Mono" },
+  { value: "mira", label: "Mira", description: "Hugeicons / Inter" },
+  { value: "luma", label: "Luma", description: "Lucide / Inter" },
+  { value: "sera", label: "Sera", description: "Lucide / Noto Sans + Playfair Display" },
+  { value: "rhea", label: "Rhea", description: "Lucide / Inter" },
+];

package/src/lib/utils/add-query-provider.ts

@@ -0,0 +1,38 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const providerSource = `"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+import { type ReactNode, useState } from "react";
+
+type QueryProviderProps = { children: ReactNode };
+
+export function QueryProvider({ children }: QueryProviderProps) {
+  const [client] = useState(() => new QueryClient({ defaultOptions: { queries: { staleTime: 60 * 1000 } } }));
+  return (
+    <QueryClientProvider client={client}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+`;
+
+const importLine = 'import { QueryProvider } from "@/components/query-provider";';
+
+export async function addQueryProvider(projectDir: string): Promise<void> {
+  await mkdir(join(projectDir, "components"), { recursive: true });
+  await writeFile(join(projectDir, "components", "query-provider.tsx"), providerSource);
+
+  const layoutPath = join(projectDir, "app", "layout.tsx");
+  const layout = await readFile(layoutPath, "utf8");
+  if (layout.includes(importLine)) {
+    return;
+  }
+  await writeFile(
+    layoutPath,
+    `${importLine}\n${layout.replace("{children}", "<QueryProvider>{children}</QueryProvider>")}`,
+  );
+}

package/src/lib/utils/extend-gitignore.ts

@@ -0,0 +1,15 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const extraSections = [["# playwright mcp", "/.playwright-mcp/"]];
+
+export async function extendGitignore(projectDir: string): Promise<void> {
+  const path = join(projectDir, ".gitignore");
+  const current = await readFile(path, "utf8").catch(() => "");
+  const missing = extraSections.filter((section) => !current.includes(section[1]));
+  if (missing.length === 0) {
+    return;
+  }
+  const body = missing.map((section) => section.join("\n")).join("\n\n");
+  await writeFile(path, `${current.trimEnd()}\n\n${body}\n`);
+}

package/src/lib/utils/write-agent-config.ts

@@ -1,19 +1,32 @@
-import { writeFile } from "node:fs/promises";
+import { access, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { FeatureId } from "../features";
+import { packageManagerCommands } from "../package-manager";
+import type { ScaffoldConfig } from "../scaffold-steps";
 
-const agentsMarkdown = `# Project notes for coding agents
+const rulesPath = new URL("../../templates/agent-rules.md", import.meta.url);
 
-- Next.js App Router with TypeScript and Tailwind CSS v4.
-- Run \`dev\` for the local server and \`build\` before shipping.
-- Keep components in \`components/\`, shared helpers in \`lib/\`.
-`;
+const exists = (path: string) =>
+  access(path).then(
+    () => true,
+    () => false,
+  );
 
-export async function writeAgentConfig(projectDir: string, features: FeatureId[]): Promise<void> {
-  if (features.includes("codex")) {
-    await writeFile(join(projectDir, "AGENTS.md"), agentsMarkdown);
+export async function writeAgentConfig(projectDir: string, config: ScaffoldConfig): Promise<void> {
+  const { features } = config;
+  const rules = (await readFile(rulesPath, "utf8"))
+    .replaceAll("{{dlx}}", packageManagerCommands[config.packageManager].dlx.join(" "))
+    .replaceAll("{{shadcnStyle}}", `base-${config.shadcnPreset}`);
+  const agentsPath = join(projectDir, "AGENTS.md");
+  const claudePath = join(projectDir, "CLAUDE.md");
+  const wantsAgents = features.includes("codex") || features.includes("claude");
+
+  if (wantsAgents) {
+    const current = (await exists(agentsPath)) ? await readFile(agentsPath, "utf8") : "";
+    if (!current.includes(rules.trim())) {
+      await writeFile(agentsPath, current ? `${current.trimEnd()}\n\n${rules}` : rules);
+    }
   }
-  if (features.includes("claude")) {
-    await writeFile(join(projectDir, "CLAUDE.md"), features.includes("codex") ? "@AGENTS.md\n" : agentsMarkdown);
+  if (features.includes("claude") && !(await exists(claudePath))) {
+    await writeFile(claudePath, "@AGENTS.md\n");
   }
 }

package/src/templates/agent-rules.md

@@ -0,0 +1,155 @@
+# Project rules
+
+## Working style
+
+### Do only what was asked
+
+Implement, confirm it works, report in a few lines, stop.
+
+- No unrequested extras — no extra files, formats, variants, fallbacks. One ask = one deliverable.
+- Verify privately (typecheck, lint, load the page). No comparison renders, previews, pixel-diffs, or scratch harnesses unless asked.
+- Mechanical edits (find/replace, rename, move) get no ceremony: no pre-survey, no occurrence counting, no re-grepping to confirm. Edit tools error on failure — that's the confirmation. Investigate first only when the change depends on it, and say why.
+- Don't narrate process, restate what you did, or list what you skipped.
+- If the request looks wrong, say so in a sentence and ask. Never implement both options or one-while-pitching-the-other.
+
+### Stop investigating and write the code
+
+Look up only what the edit can't be written without, then write it.
+
+- Never reverse-engineer a live system: no scraping the deployed site, grepping its bundles, fetching extra pages, or diffing responses. One call to the pointed-at endpoint to see its shape is the whole budget.
+- Missing detail? Pick the obvious mapping or omit the field, note it in one line, let the user decide. Don't hunt.
+- A one-line-of-UI detail (label, fallback, nice-to-have) is not worth a single extra request.
+- No background/parallel commands for questions the task doesn't hinge on.
+- Several turns of reading without editing = off track. Write the code and ask what's unclear.
+
+### Check the API before building behaviour
+
+`components/ui` wraps Base UI. Before adding/changing behaviour (open/close, hover/focus, positioning, delays, keyboard nav, typeahead, portals, animation state, form wiring), read `node_modules/@base-ui/react/docs/react/components/` and `.../handbook/` — it's almost always an existing prop, part, or data attribute. Same for Next.js: read `node_modules/next/dist/docs/` before hand-rolling navigation, caching, data loading, metadata, redirects, image/font handling. Don't trust memory of either API — read the file. Custom implementations only after docs prove the built-in can't, noted in one line.
+
+### Verification never writes into the repo
+
+All check by-products (screenshots, snapshots, logs, scratch scripts, sample payloads) go in a temp dir outside the tree — never repo root, `.playwright-mcp/`, or `screenshots/`. Always pass tools an absolute path outside the repo. Delete artifacts when done (`.gitignore` is not cleanup). Only requested files remain.
+
+## Git
+
+### Never discard unrelated working tree changes
+
+The user edits files while agents run. Uncommitted changes are real work.
+
+- Never `git checkout`/`restore`/`reset --hard`/`stash`/`clean` on changes you didn't make. Revert your own edits line-by-line only.
+- Don't "tidy" others' modifications, even if they look stale or half-finished.
+- Re-read files before editing — they may have changed. Never write from a stale copy.
+- Collision with someone else's change: stop and ask.
+- Stage specific paths only. Never `git add -A` / `git add .`.
+- Never create a branch unless asked in that request. "Commit this" = commit on the checked-out branch, including `main`.
+
+### Prove a reference is dead before deleting
+
+`rg` / `rg --files` first, for any file, export, dependency, registry entry, test, or doc you're about to remove — this is the one deletion that earns a pre-survey. Remove every stale reference in the same pass.
+
+## Files and structure
+
+### One component per file
+
+Each component gets its own file named after it (`BrandThumbnail` → `brand-thumbnail.tsx`). No second component in a file, even a small private one — split it out, export/import by name. Exception: `components/ui` keeps whatever the registry shipped.
+
+### Filenames are `<domain>-<role>`
+
+Component directories are flat, so the first token is the only grouping there is. Spend it on the domain, put the role last: `brand-card`, `product-list-carousel`, `search-filter-section`. Common roles — `card`, `carousel`, `chip`, `dialog`, `filter`, `form`, `group`, `header`, `item`, `list`, `menu`, `nav`, `panel`, `selector`, `skeleton`, `table`, `thumbnail`, `tree`. Reuse one before inventing a word.
+
+**The domain prefix is always singular**, whatever the component holds: `brand-nav` (takes `Brand[]`), `category-cloud-list`, `product-list-carousel`. Plurality is the suffix's job. One domain sorts as one contiguous block — `brands-nav` next to `brand-card` is the failure this prevents.
+
+### Dialogs and forms live in their own directories
+
+A `*-dialog.tsx` file goes in `components/dialogs`, a `*-form.tsx` file in `components/forms`, imported as `@/components/dialogs/cart-quote-dialog` and `@/components/forms/address-form`. Never create either anywhere else, and move any you find. Everything else here still applies: one component per file, `<domain>-<role>` filenames, singular domain prefix.
+
+A dialog or form that fetches splits the same way a section does, and both halves stay in the same directory. Its skeleton follows it too: `account-profile-form-skeleton` sits beside `account-profile-form` in `components/forms`.
+
+### A section that fetches splits in two
+
+When the render half needs `'use client'`, or is shared by more than one section, it moves to its own file. The `section-*` parent does the `await`; the child is named for **what it renders**, never a prefix-only variation of its parent:
+
+| parent (fetches) | child (renders) |
+| --- | --- |
+| `section-faq` | `faq-accordion` |
+| `section-hero` | `hero-carousel` |
+| `section-related-products` | `product-list-carousel` |
+
+`section-faq.tsx` beside `faqs.tsx` is the anti-pattern: nothing in the name says which one holds the `await`.
+
+A Suspense fallback occupying a section's band is itself a section — `section-product-about-skeleton` sorts next to `section-product-about`.
+
+### Custom hooks live in lib/hooks
+
+One file per hook, named after it (`useHeaderPopup` → `lib/hooks/use-header-popup.ts`). Never define hooks elsewhere; move any found. Exception: hooks shipped with shadcn components in `components/ui`.
+
+### Helpers live in lib/utils
+
+One file per helper, named after it (`cn` → `lib/utils/cn.ts`). Never define helpers elsewhere; move any found. Read `lib/utils` before writing a new one — reuse or extend beats adding. Exception: `components/ui`.
+
+Most helpers should never be written. A helper earns its place by holding a decision — branching, a rule, a non-obvious transform, a thought-through constant. One-expression bodies get inlined. Don't write:
+
+- Wrappers around one call (`formatPrice` = `n.toFixed(2)`, `isEmpty` = `!arr.length`).
+- Aliases (another function with reordered args or a filled default).
+- Single-use one-liners — put them at the call site.
+- Speculative utils — write it when the second caller appears.
+- What the platform/deps already do — check `Intl`, `URL`, `URLSearchParams`, array/string methods, and `package.json` libs first.
+
+`lib/utils` is shared surface: genuinely reusable, named for what it returns, correct beyond the prompting call site. Can't name it without `handle`/`process`/`data`/`helper`/bare `format`? Don't write it. When touching code that calls a bad helper, inline it and delete the file.
+
+### Types live in /types
+
+Every `type`/`interface` goes in a domain file (`Product` → `types/product.ts`); move any found elsewhere. Import via `import type { … } from '@/types/<domain>'`. Exception: `components/ui`. Inline annotations aren't declarations and stay put.
+
+## Types
+
+### No escape-hatch types
+
+Every value has a shape — write it. Banned everywhere (declarations, annotations, generics, casts, returns): `unknown`, `any`, `Record<string, unknown|any>`, `{ [key: string]: unknown }`, `object`, `{}`, `Function`, `unknown[]`, `any[]`, and laundering casts (`data as Product`, `as unknown as`).
+
+If the shape isn't obvious, find it: Schema, API response, library types in `node_modules`, or the producing code. Untyped boundary data gets a declared type plus a parse/narrow step. Retype anything from shadcn/registries/codegen before committing. Generic params are fine (`<T>(items: T[]) => T[]`); constrain when the body needs a property. `unknown` is allowed only in `catch`, narrowed before use.
+
+### Empty array / null is still a real field
+
+Empty samples prove nothing about a field's shape. Type fields for the data they'll hold: `tierPrices: TierPrice[] | null`, never `never[]`, `[]`, `null`, or dropped.
+
+- Don't sample record after record hoping a field fills in, or report "empty in N responses" as evidence.
+- Unobserved element shape: infer from the field's name and siblings, declare in `/types`, flag as unconfirmed in one line. Mock data is never the fallback — fetch a different record.
+
+## UI
+
+### Use the registry before writing a primitive
+
+Never handwrite a primitive. Stop at the first hit:
+
+1. Already in `components/ui` → use it (e.g. shadcn `Button`, not raw `<button>`).
+2. In the official shadcn registry → `{{dlx}} shadcn@latest add <component>`. Check the registry, don't trust memory — it's grown, and `components.json` (`{{shadcnStyle}}`) pulls Base UI variants. Never hand-copy source from docs or rebuild what the registry ships.
+3. Nothing fits → write it, and say in one line what you searched and why nothing worked.
+
+### Size comes from the size prop
+
+Never resize a `components/ui` component with utilities — no `size-8`/`h-9`/`w-12`, no padding/text-size overrides, no inline width/height. Use the closest existing `size` variant (read the component file for the current list). Leave icons unsized — variants set them. No new variants, no widening existing ones, no overrides for in-between pixel values. `className` keeps margins, alignment, grid placement, colour.
+
+### Text sizes come from the scale
+
+No arbitrary font sizes — no `text-[13px]`, `text-[0.8rem]`, no inline `fontSize`. Use the scale: `text-xs`, `text-sm`, `text-base`, `text-lg`, up. If `app/globals.css` retunes any `--text-*` token, read those values first; the matching class may not be the one its name suggests. If a size is genuinely missing, add a `--text-*` token in `globals.css`, never inline it. Applies to shadcn/registry/Figma imports.
+
+### Conditional classes use object style
+
+In `cn()`, conditionals are objects keyed by class string — never `&&` or ternaries:
+
+```tsx
+cn('flex flex-col gap-3', { 'items-center text-center': align === 'center' }, className)
+```
+
+A ternary becomes two entries (`{ 'bg-brand': reached, 'bg-border': !reached }`) — don't lean on tailwind-merge for conflicts a condition can state. Unconditional classes stay plain strings; passed-through `className` stays last so it wins merges.
+
+### Underline pairs with underline-offset-4
+
+Every `underline` gets `underline-offset-4`, including variants (`hover:underline underline-offset-4` — offset stays unprefixed). Fix anything pulled in that underlines without it.
+
+## Comments
+
+### Comments default to zero
+
+A comment is earned only by an external fact the code can't carry: an API/service/tool quirk, an upstream-bug workaround, or why a non-obvious constant has its value. Never narrate code, label sections, restate names in JSDoc, mark changes, record refactor history, or address the reviewer. Delete commented-out code; when unsure, delete; prefer renaming over explaining. Machine directives are not comments and stay: `oxlint-disable*`, `ts-expect-error`, `AUTO-GENERATED` banners.

package/src/components/package-manager-prompt.tsx

@@ -1,38 +0,0 @@
-import { useKeyboard } from "@opentui/react";
-import { useState } from "react";
-import { type PackageManager, packageManagers } from "../lib/package-manager";
-
-type PackageManagerPromptProps = { initialValue: PackageManager; onSelect: (packageManager: PackageManager) => void };
-
-export function PackageManagerPrompt({ initialValue, onSelect }: PackageManagerPromptProps) {
-  const [index, setIndex] = useState(Math.max(0, packageManagers.indexOf(initialValue)));
-
-  useKeyboard((key) => {
-    if (key.name === "up" || key.name === "k") {
-      setIndex((current) => (current + packageManagers.length - 1) % packageManagers.length);
-    } else if (key.name === "down" || key.name === "j") {
-      setIndex((current) => (current + 1) % packageManagers.length);
-    } else if (key.name === "return") {
-      onSelect(packageManagers[index]);
-    }
-  });
-
-  return (
-    <box flexDirection="column">
-      <text>
-        <span fg="#a78bfa">◆</span>  <strong>Package manager</strong>
-      </text>
-      {packageManagers.map((value, i) => (
-        <text key={value}>
-          <span fg="#a78bfa">│  </span>
-          {i === index ? <span fg="#4ade80">◉ </span> : <span fg="#555555">○ </span>}
-          <span fg={i === index ? "#ffffff" : "#888888"}>{value}</span>
-        </text>
-      ))}
-      <text>
-        <span fg="#a78bfa">│  </span>
-        <span fg="#666666">↑↓ to move · Enter to continue · Esc to go back</span>
-      </text>
-    </box>
-  );
-}