@dinakars777/create-nexus 1.0.0

package/README.md

@@ -0,0 +1,40 @@
+# 🧠 create-nexus
+
+> **The Ultimate Agent-Native Boilerplate Generator.**
+
+Most Next.js boilerplates are optimized for human readability.
+**Project Nexus** is optimized to be perfectly indexed, mutated, and scaled by AI Coding Agents (Cursor, Claude, Devin) with *zero hallucinations*.
+
+## The Problem
+When you ask an AI Agent to "build a feature" in a standard Next.js codebase, it hallucinates. It mixes Pages Router with App Router, it writes raw SQL instead of using your ORM, or it bypasses your API layer entirely to write Server Actions in the UI. 
+
+## The Solution
+`create-nexus` generates a fortress. It scaffolds a high-density, strictly-typed environment (Next.js, Hono, Drizzle, Zod) that includes a built-in **Context Control Plane** explicitly designed to govern AI behavior.
+
+### 📦 The Tech Stack
+*   **Frontend:** Next.js (App Router) + Tailwind CSS
+*   **API:** Hono RPC (End-to-End Type Safety)
+*   **Database:** Drizzle ORM + Postgres
+*   **Validation:** Strict Zod Boundaries
+
+### 🤖 The Agent-Native Architecture
+When you run the generator, you aren't just getting React components. You get:
+
+1.  **The `.agent/` Control Directory**: Contains global `rules.md`, an architectural `project-map.json`, and a `scratchpad.md` for the agent to "think" out loud.
+2.  **The Twin-File System**: Every major directory (`src/app`, `src/db`) contains a `CONCEPTS.md`. This defines the Business Logic vs. Implementation boundaries so the agent understands the "why" and doesn't guess context.
+3.  **Strict Type-Safety Walls**: Absolute zero `any` types. Every API route uses `zValidator`. If an agent hallucinates an API shape, the Typescript compiler crashes, forcing the agent to read the error and fix itself.
+4.  **Verification Hooks**: Pre-configured Husky pre-commit hooks run `tsc --noEmit`. If the agent breaks the build, the Git commit natively fails, forcing it to loop until structurally sound.
+5.  **MCP Stub**: An integrated Model Context Protocol server stub (`server/mcp`) allowing local agents to securely query database schemas without reading thousands of lines of code.
+
+## Quickstart
+
+Instantly generate your Agent-Native workspace:
+
+```bash
+npx @dinakars777/create-nexus
+```
+
+Follow the interactive prompts to name your project. The CLI will handle directory scaffolding, Git initialization, and NPM dependency installations.
+
+## License
+MIT

package/dist/index.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { intro, outro, spinner, text, confirm, isCancel } from "@clack/prompts";
+import { Command } from "commander";
+import pc from "picocolors";
+
+// src/generator.ts
+import fs from "fs-extra";
+import path from "path";
+
+// src/templates/agent.ts
+var agentRulesTemplate = `# Global Agent Rules
+- **Verify Before Commit:** Always run \`pnpm check\` (or \`npm run check\`) which triggers tsc and vitest after a change. Do not commit failing code.
+- **Strict Typing:** Never use \`any\`. Use Zod for all validations.
+- **Twin-Files:** If you create a new directory, you MUST create a \`CONCEPTS.md\` explaining its business logic and boundaries.
+- **Architecture Limits:** Do not import UI components into the API layer. Do not import Drizzle directly into the Next.js React UI layer.
+- **Think First:** Before making massive destructive changes, write your plan in \`.agent/scratchpad.md\`.
+`;
+var agentProjectMapTemplate = `{
+  "name": "nexus-app",
+  "architecture": {
+    "frontend": "Next.js App Router (React Server Components)",
+    "api": "Hono RPC",
+    "database": "Drizzle ORM + SQLite",
+    "validation": "Zod"
+  },
+  "directories": {
+    "src/app": "Next.js Routing and React UI Pages",
+    "src/server": "Hono API backend and RCP routes",
+    "src/db": "Drizzle schema operations",
+    "server/mcp": "Model Context Protocol stubs"
+  }
+}
+`;
+var agentScratchpadTemplate = `# Agent Scratchpad
+*Use this file to think out loud, draft complex refactors, or save temporary snippets before applying them to the main codebase.*
+
+## Current Objective
+...
+`;
+
+// src/templates/twin.ts
+var twinAppConceptsTemplate = `# CONCEPTS: Frontend (src/app)
+
+## Business Logic
+This directory contains the user-facing React application. It is responsible purely for data presentation and optimistic UI updates.
+
+## Boundaries
+- **DO NOT** perform direct database queries (Drizzle) from here.
+- **DO NOT** define raw Zod schemas for the database here.
+- **DO** use the generated Hono RPC client (e.g., \`hc\`) to communicate with the \`src/server\` API.
+- All components should default to React Server Components unless interactive hooks (useState, useEffect) are strictly required (use \`"use client"\`).
+`;
+var twinServerConceptsTemplate = `# CONCEPTS: API Backend (src/server)
+
+## Business Logic
+This directory houses the Hono API routes. This is the exclusive gateway for all data mutations and retrievals.
+
+## Boundaries
+- **MUST** validate all incoming payloads using \`zValidator\` with Zod.
+- **MUST** export the \`AppType\` router type so the Next.js frontend can consume the RPC client with end-to-end type safety.
+- **DO NOT** import React or UI components into this layer.
+`;
+var twinDbConceptsTemplate = `# CONCEPTS: Database Layer (src/db)
+
+## Business Logic
+This directory contains the single source of truth for the database schema using Drizzle ORM.
+
+## Boundaries
+- **MUST** export Drizzle Select/Insert schemas (e.g., \`createInsertSchema\`) using \`drizzle-zod\`.
+- This layer does not execute business logic; it strictly defines the schema shapes and relationships.
+`;
+
+// src/templates/stack.ts
+var honoServerTemplate = `import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+import { z } from 'zod';
+import { db } from '../db';
+import { users } from '../db/schema';
+
+const app = new Hono().basePath('/api');
+
+// @ai-intent: STRICT ZOD VALIDATION REQUIRED FOR ALL ROUTES
+const createUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+const routes = app
+  .get('/users', async (c) => {
+    const allUsers = await db.select().from(users);
+    return c.json(allUsers);
+  })
+  .post('/users', zValidator('json', createUserSchema), async (c) => {
+    const { name, email } = c.req.valid('json');
+    const result = await db.insert(users).values({ name, email }).returning();
+    return c.json(result[0], 201);
+  });
+
+export type AppType = typeof routes;
+export default app;
+`;
+var drizzleSchemaTemplate = `import { pgTable, text, serial, timestamp } from 'drizzle-orm/pg-core';
+
+// @ai-intent: SINGLE SOURCE OF TRUTH. Do not write raw SQL.
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  createdAt: timestamp('created_at').defaultNow(),
+});
+`;
+var drizzleDbTemplate = `import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+
+const queryClient = postgres(process.env.DATABASE_URL || 'postgres://localhost:5432/nexus');
+export const db = drizzle(queryClient);
+`;
+var nextjsPageTemplate = `import { hc } from 'hono/client';
+import { type AppType } from '../server';
+
+// @ai-intent: HONO RPC CLIENT INSTANTIATION
+// Agents MUST use this \`client\` to interact with the backend to preserve end-to-end type safety.
+const client = hc<AppType>('http://localhost:3000');
+
+export default async function Home() {
+  const res = await client.api.users.$get();
+  const users = await res.json();
+
+  return (
+    <main className="min-h-screen bg-black text-white p-24 font-sans">
+      <div className="max-w-xl mx-auto space-y-8">
+        <h1 className="text-4xl font-bold tracking-tight">Project Nexus \u{1F9E0}</h1>
+        <p className="text-zinc-400">
+          Agent-Native Boilerplate initialized. Next.js, Hono, Drizzle, and Zod perfectly aligned.
+        </p>
+        
+        <div className="p-6 border border-zinc-800 rounded-lg bg-zinc-950">
+          <h2 className="text-xl font-semibold mb-4">Database Users</h2>
+          {users.length === 0 ? (
+            <p className="text-zinc-500">No users found. Try adding one via the API.</p>
+          ) : (
+            <ul className="space-y-2">
+              {users.map((u: any) => (
+                <li key={u.id} className="text-zinc-300">\u2022 {u.name} ({u.email})</li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </div>
+    </main>
+  );
+}
+`;
+
+// src/templates/mcp.ts
+var mcpServerTemplate = `import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { execSync } from 'child_process';
+import fs from 'fs';
+
+// @ai-intent: MCP SERVER STUB
+// Agents can connect to this server via stdio to execute read-only queries against the environment.
+
+const server = new Server(
+  { name: "nexus-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "get_drizzle_schema",
+        description: "Returns the raw text of the current Drizzle database schema to maintain context without hallucinating.",
+        inputSchema: { type: "object", properties: {}, required: [] },
+      },
+      {
+        name: "check_build_health",
+        description: "Runs typescript compiler checks to verify if the codebase currently has any type errors.",
+        inputSchema: { type: "object", properties: {}, required: [] },
+      }
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "get_drizzle_schema") {
+    try {
+      const schema = fs.readFileSync('./src/db/schema.ts', 'utf-8');
+      return { toolResult: schema };
+    } catch {
+      return { toolResult: "Schema file not found." };
+    }
+  }
+  
+  if (request.params.name === "check_build_health") {
+    try {
+      const output = execSync('npx tsc --noEmit', { encoding: 'utf-8' });
+      return { toolResult: output || "Build is perfectly healthy. No type errors." };
+    } catch (e: any) {
+      return { toolResult: \`Type errors detected:\\n\${e.stdout}\` };
+    }
+  }
+
+  throw new Error("Tool not found");
+});
+
+const transport = new StdioServerTransport();
+server.connect(transport).catch(console.error);
+`;
+
+// src/generator.ts
+async function generateBoilerplate(projectName) {
+  const targetDir = path.resolve(process.cwd(), projectName);
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Directory ${projectName} already exists.`);
+  }
+  await fs.ensureDir(targetDir);
+  const dirs = [
+    "src/app",
+    "src/server",
+    "src/db",
+    "server/mcp",
+    ".agent",
+    ".husky"
+  ];
+  for (const dir of dirs) {
+    await fs.ensureDir(path.join(targetDir, dir));
+  }
+  await fs.writeFile(path.join(targetDir, ".agent/rules.md"), agentRulesTemplate);
+  await fs.writeFile(path.join(targetDir, ".agent/project-map.json"), agentProjectMapTemplate);
+  await fs.writeFile(path.join(targetDir, ".agent/scratchpad.md"), agentScratchpadTemplate);
+  await fs.writeFile(path.join(targetDir, "src/app/CONCEPTS.md"), twinAppConceptsTemplate);
+  await fs.writeFile(path.join(targetDir, "src/server/CONCEPTS.md"), twinServerConceptsTemplate);
+  await fs.writeFile(path.join(targetDir, "src/db/CONCEPTS.md"), twinDbConceptsTemplate);
+  await fs.writeFile(path.join(targetDir, "server/mcp/index.ts"), mcpServerTemplate);
+  await fs.writeFile(path.join(targetDir, "src/server/index.ts"), honoServerTemplate);
+  await fs.writeFile(path.join(targetDir, "src/db/schema.ts"), drizzleSchemaTemplate);
+  await fs.writeFile(path.join(targetDir, "src/db/index.ts"), drizzleDbTemplate);
+  await fs.writeFile(path.join(targetDir, "src/app/page.tsx"), nextjsPageTemplate);
+  const packageJson = {
+    name: projectName,
+    version: "0.1.0",
+    private: true,
+    scripts: {
+      "dev": "next dev",
+      "build": "next build",
+      "start": "next start",
+      "lint": "next lint",
+      "check": "tsc --noEmit",
+      "db:push": "drizzle-kit push",
+      "prepare": "husky install"
+    },
+    dependencies: {
+      "next": "14.2.3",
+      "react": "^18",
+      "react-dom": "^18",
+      "hono": "^4.3.0",
+      "zod": "^3.23.0",
+      "@hono/zod-validator": "^0.2.1",
+      "drizzle-orm": "^0.30.0",
+      "postgres": "^3.4.4",
+      "@modelcontextprotocol/sdk": "^1.27.1"
+    },
+    devDependencies: {
+      "typescript": "^5",
+      "@types/node": "^20",
+      "@types/react": "^18",
+      "@types/react-dom": "^18",
+      "postcss": "^8",
+      "tailwindcss": "^3.4.1",
+      "drizzle-kit": "^0.21.0",
+      "husky": "^9.0.0",
+      "lint-staged": "^15.2.0"
+    },
+    "lint-staged": {
+      "*.ts?(x)": [
+        "tsc --noEmit"
+      ]
+    }
+  };
+  await fs.writeJson(path.join(targetDir, "package.json"), packageJson, { spaces: 2 });
+  const tsconfig = {
+    "compilerOptions": {
+      "lib": ["dom", "dom.iterable", "esnext"],
+      "allowJs": true,
+      "skipLibCheck": true,
+      "strict": true,
+      "noEmit": true,
+      "esModuleInterop": true,
+      "module": "esnext",
+      "moduleResolution": "bundler",
+      "resolveJsonModule": true,
+      "isolatedModules": true,
+      "jsx": "preserve",
+      "incremental": true,
+      "plugins": [
+        {
+          "name": "next"
+        }
+      ],
+      "paths": {
+        "@/*": ["./src/*"]
+      }
+    },
+    "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+    "exclude": ["node_modules"]
+  };
+  await fs.writeJson(path.join(targetDir, "tsconfig.json"), tsconfig, { spaces: 2 });
+  const huskyPreCommit = `#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged
+npm run check
+`;
+  await fs.writeFile(path.join(targetDir, ".husky/pre-commit"), huskyPreCommit);
+}
+
+// src/index.ts
+import { execa } from "execa";
+var program = new Command();
+program.name("create-nexus").description("Scaffold the ultimate Agent-Native Boilerplate.").version("1.0.0");
+program.action(async () => {
+  console.log();
+  intro(pc.inverse(pc.bold(" \u{1F9E0} CREATE NEXUS: Agent-Native Stack ")));
+  const projectName = await text({
+    message: "What is your project named?",
+    placeholder: "my-agent-app",
+    validate(value) {
+      if (!value || value.length === 0) return "Project name is required!";
+      if (/^[a-zA-Z0-9-]+$/.test(value) === false) return "Project name can only contain letters, numbers, and dashes.";
+    }
+  });
+  if (isCancel(projectName)) {
+    outro("Operation cancelled.");
+    process.exit(0);
+  }
+  const s = spinner();
+  s.start(`Scaffolding Agent-Native architecture into ${projectName}...`);
+  try {
+    await generateBoilerplate(projectName);
+    s.stop(pc.green("\u2713 Scaffold instantiated successfully."));
+  } catch (err) {
+    s.stop(pc.red("\u2716 Failed to generate project."));
+    console.error(pc.red(err.message));
+    process.exit(1);
+  }
+  console.log();
+  console.log(pc.bold("Included in this High-Density Stack:"));
+  console.log(pc.cyan("  \u2022 Next.js App Router") + " (Frontend)");
+  console.log(pc.cyan("  \u2022 Hono RPC") + " (Type-safe API Backend)");
+  console.log(pc.cyan("  \u2022 Drizzle ORM + SQLite") + " (Strict Zod Schemas)");
+  console.log(pc.cyan("  \u2022 The Twin-File Architecture") + " (CONCEPTS.md context layer)");
+  console.log(pc.cyan("  \u2022 Integrated MCP Stub") + " (server/mcp for Agent querying)");
+  console.log(pc.cyan("  \u2022 Husky + tsc") + " (Strict commit verification hooks)");
+  console.log();
+  const installDeps = await confirm({
+    message: "Would you like to install dependencies now? (npm install)",
+    initialValue: true
+  });
+  if (isCancel(installDeps)) {
+    outro("Operation cancelled.");
+    process.exit(0);
+  }
+  if (installDeps) {
+    s.start("Installing dependencies via npm...");
+    try {
+      await execa("npm", ["install"], { cwd: projectName });
+      s.stop(pc.green("\u2713 Dependencies installed."));
+    } catch {
+      s.stop(pc.red("\u2716 Failed to install dependencies. You can run npm install manually later."));
+    }
+  }
+  const initGit = await confirm({
+    message: "Initialize a new Git repository?",
+    initialValue: true
+  });
+  if (!isCancel(initGit) && initGit) {
+    try {
+      await execa("git", ["init"], { cwd: projectName });
+      console.log(pc.green("\u2713 Git repository initialized."));
+    } catch {
+    }
+  }
+  console.log();
+  console.log(pc.bgGreen(" SUCCESS! ") + ` Project ${projectName} is ready for an AI Agent to dominate.`);
+  console.log("Next steps:");
+  console.log(pc.bold(`  cd ${projectName}`));
+  console.log(pc.bold("  npm run dev"));
+  outro("Good luck building!");
+});
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dinakars777/create-nexus",
+  "version": "1.0.0",
+  "description": "Scaffold the ultimate Agent-Native Boilerplate. Next.js, Hono, Drizzle, Zod, with built-in .agent control plane.",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "create-nexus": "dist/index.js",
+    "create-nexus-app": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsup watch",
+    "build": "tsup src/index.ts --format esm --clean"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "boilerplate",
+    "nextjs",
+    "hono",
+    "drizzle"
+  ],
+  "author": "Dinakar Sarbada",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "commander": "^11.1.0",
+    "execa": "^8.0.1",
+    "fs-extra": "^11.2.0",
+    "picocolors": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.2"
+  }
+}

package/src/generator.ts

@@ -0,0 +1,133 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { agentRulesTemplate, agentProjectMapTemplate, agentScratchpadTemplate } from './templates/agent';
+import { twinAppConceptsTemplate, twinServerConceptsTemplate, twinDbConceptsTemplate } from './templates/twin';
+import { honoServerTemplate, drizzleSchemaTemplate, drizzleDbTemplate, nextjsPageTemplate } from './templates/stack';
+import { mcpServerTemplate } from './templates/mcp';
+
+export async function generateBoilerplate(projectName: string) {
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Directory ${projectName} already exists.`);
+  }
+
+  // 1. Core Directory Scaffolding
+  await fs.ensureDir(targetDir);
+  const dirs = [
+    'src/app',
+    'src/server',
+    'src/db',
+    'server/mcp',
+    '.agent',
+    '.husky'
+  ];
+
+  for (const dir of dirs) {
+    await fs.ensureDir(path.join(targetDir, dir));
+  }
+
+  // 2. The Agent Control Directory
+  await fs.writeFile(path.join(targetDir, '.agent/rules.md'), agentRulesTemplate);
+  await fs.writeFile(path.join(targetDir, '.agent/project-map.json'), agentProjectMapTemplate);
+  await fs.writeFile(path.join(targetDir, '.agent/scratchpad.md'), agentScratchpadTemplate);
+
+  // 3. The Twin-File System (CONCEPTS.md)
+  await fs.writeFile(path.join(targetDir, 'src/app/CONCEPTS.md'), twinAppConceptsTemplate);
+  await fs.writeFile(path.join(targetDir, 'src/server/CONCEPTS.md'), twinServerConceptsTemplate);
+  await fs.writeFile(path.join(targetDir, 'src/db/CONCEPTS.md'), twinDbConceptsTemplate);
+
+  // 4. MCP Server Stub
+  await fs.writeFile(path.join(targetDir, 'server/mcp/index.ts'), mcpServerTemplate);
+
+  // 5. Stack Templates
+  await fs.writeFile(path.join(targetDir, 'src/server/index.ts'), honoServerTemplate);
+  await fs.writeFile(path.join(targetDir, 'src/db/schema.ts'), drizzleSchemaTemplate);
+  await fs.writeFile(path.join(targetDir, 'src/db/index.ts'), drizzleDbTemplate);
+  await fs.writeFile(path.join(targetDir, 'src/app/page.tsx'), nextjsPageTemplate);
+
+  // 6. Base Package Config & Verification Hooks (Husky)
+  const packageJson = {
+    name: projectName,
+    version: "0.1.0",
+    private: true,
+    scripts: {
+      "dev": "next dev",
+      "build": "next build",
+      "start": "next start",
+      "lint": "next lint",
+      "check": "tsc --noEmit",
+      "db:push": "drizzle-kit push",
+      "prepare": "husky install"
+    },
+    dependencies: {
+      "next": "14.2.3",
+      "react": "^18",
+      "react-dom": "^18",
+      "hono": "^4.3.0",
+      "zod": "^3.23.0",
+      "@hono/zod-validator": "^0.2.1",
+      "drizzle-orm": "^0.30.0",
+      "postgres": "^3.4.4",
+      "@modelcontextprotocol/sdk": "^1.27.1"
+    },
+    devDependencies: {
+      "typescript": "^5",
+      "@types/node": "^20",
+      "@types/react": "^18",
+      "@types/react-dom": "^18",
+      "postcss": "^8",
+      "tailwindcss": "^3.4.1",
+      "drizzle-kit": "^0.21.0",
+      "husky": "^9.0.0",
+      "lint-staged": "^15.2.0"
+    },
+    "lint-staged": {
+      "*.ts?(x)": [
+        "tsc --noEmit"
+      ]
+    }
+  };
+
+  await fs.writeJson(path.join(targetDir, 'package.json'), packageJson, { spaces: 2 });
+
+  // TSConfig
+  const tsconfig = {
+    "compilerOptions": {
+      "lib": ["dom", "dom.iterable", "esnext"],
+      "allowJs": true,
+      "skipLibCheck": true,
+      "strict": true,
+      "noEmit": true,
+      "esModuleInterop": true,
+      "module": "esnext",
+      "moduleResolution": "bundler",
+      "resolveJsonModule": true,
+      "isolatedModules": true,
+      "jsx": "preserve",
+      "incremental": true,
+      "plugins": [
+        {
+          "name": "next"
+        }
+      ],
+      "paths": {
+        "@/*": ["./src/*"]
+      }
+    },
+    "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+    "exclude": ["node_modules"]
+  };
+  await fs.writeJson(path.join(targetDir, 'tsconfig.json'), tsconfig, { spaces: 2 });
+
+  // Husky Pre-commit hook
+  const huskyPreCommit = `#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged
+npm run check
+`;
+  await fs.writeFile(path.join(targetDir, '.husky/pre-commit'), huskyPreCommit);
+  // Ensure the hook is executable (not natively supported by fs.writeFile easily cross-platform, but good enough for a generated boilerplate before install)
+
+}

package/src/index.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { intro, outro, spinner, text, confirm, isCancel } from '@clack/prompts';
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { generateBoilerplate } from './generator';
+import { execa } from 'execa';
+
+const program = new Command();
+
+program
+  .name('create-nexus')
+  .description('Scaffold the ultimate Agent-Native Boilerplate.')
+  .version('1.0.0');
+
+program.action(async () => {
+  console.log();
+  intro(pc.inverse(pc.bold(' 🧠 CREATE NEXUS: Agent-Native Stack ')));
+
+  const projectName = await text({
+    message: 'What is your project named?',
+    placeholder: 'my-agent-app',
+    validate(value) {
+      if (!value || value.length === 0) return 'Project name is required!';
+      if (/^[a-zA-Z0-9-]+$/.test(value) === false) return 'Project name can only contain letters, numbers, and dashes.';
+    },
+  });
+
+  if (isCancel(projectName)) {
+    outro('Operation cancelled.');
+    process.exit(0);
+  }
+
+  const s = spinner();
+  s.start(`Scaffolding Agent-Native architecture into ${projectName}...`);
+
+  try {
+    await generateBoilerplate(projectName as string);
+    s.stop(pc.green('✓ Scaffold instantiated successfully.'));
+  } catch (err: any) {
+    s.stop(pc.red('✖ Failed to generate project.'));
+    console.error(pc.red(err.message));
+    process.exit(1);
+  }
+
+  console.log();
+  console.log(pc.bold('Included in this High-Density Stack:'));
+  console.log(pc.cyan('  • Next.js App Router') + ' (Frontend)');
+  console.log(pc.cyan('  • Hono RPC') + ' (Type-safe API Backend)');
+  console.log(pc.cyan('  • Drizzle ORM + SQLite') + ' (Strict Zod Schemas)');
+  console.log(pc.cyan('  • The Twin-File Architecture') + ' (CONCEPTS.md context layer)');
+  console.log(pc.cyan('  • Integrated MCP Stub') + ' (server/mcp for Agent querying)');
+  console.log(pc.cyan('  • Husky + tsc') + ' (Strict commit verification hooks)');
+  console.log();
+
+  const installDeps = await confirm({
+    message: 'Would you like to install dependencies now? (npm install)',
+    initialValue: true,
+  });
+
+  if (isCancel(installDeps)) {
+    outro('Operation cancelled.');
+    process.exit(0);
+  }
+
+  if (installDeps) {
+    s.start('Installing dependencies via npm...');
+    try {
+      await execa('npm', ['install'], { cwd: projectName as string });
+      s.stop(pc.green('✓ Dependencies installed.'));
+    } catch {
+      s.stop(pc.red('✖ Failed to install dependencies. You can run npm install manually later.'));
+    }
+  }
+
+  const initGit = await confirm({
+    message: 'Initialize a new Git repository?',
+    initialValue: true,
+  });
+
+  if (!isCancel(initGit) && initGit) {
+      try {
+          await execa('git', ['init'], { cwd: projectName as string });
+          console.log(pc.green('✓ Git repository initialized.'));
+      } catch {}
+  }
+
+  console.log();
+  console.log(pc.bgGreen(' SUCCESS! ') + ` Project ${projectName} is ready for an AI Agent to dominate.`);
+  console.log('Next steps:');
+  console.log(pc.bold(`  cd ${projectName}`));
+  console.log(pc.bold('  npm run dev'));
+  
+  outro('Good luck building!');
+});
+
+program.parse(process.argv);

package/src/templates/agent.ts

@@ -0,0 +1,31 @@
+export const agentRulesTemplate = `# Global Agent Rules
+- **Verify Before Commit:** Always run \`pnpm check\` (or \`npm run check\`) which triggers tsc and vitest after a change. Do not commit failing code.
+- **Strict Typing:** Never use \`any\`. Use Zod for all validations.
+- **Twin-Files:** If you create a new directory, you MUST create a \`CONCEPTS.md\` explaining its business logic and boundaries.
+- **Architecture Limits:** Do not import UI components into the API layer. Do not import Drizzle directly into the Next.js React UI layer.
+- **Think First:** Before making massive destructive changes, write your plan in \`.agent/scratchpad.md\`.
+`;
+
+export const agentProjectMapTemplate = `{
+  "name": "nexus-app",
+  "architecture": {
+    "frontend": "Next.js App Router (React Server Components)",
+    "api": "Hono RPC",
+    "database": "Drizzle ORM + SQLite",
+    "validation": "Zod"
+  },
+  "directories": {
+    "src/app": "Next.js Routing and React UI Pages",
+    "src/server": "Hono API backend and RCP routes",
+    "src/db": "Drizzle schema operations",
+    "server/mcp": "Model Context Protocol stubs"
+  }
+}
+`;
+
+export const agentScratchpadTemplate = `# Agent Scratchpad
+*Use this file to think out loud, draft complex refactors, or save temporary snippets before applying them to the main codebase.*
+
+## Current Objective
+...
+`;

package/src/templates/mcp.ts

@@ -0,0 +1,56 @@
+export const mcpServerTemplate = `import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { execSync } from 'child_process';
+import fs from 'fs';
+
+// @ai-intent: MCP SERVER STUB
+// Agents can connect to this server via stdio to execute read-only queries against the environment.
+
+const server = new Server(
+  { name: "nexus-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "get_drizzle_schema",
+        description: "Returns the raw text of the current Drizzle database schema to maintain context without hallucinating.",
+        inputSchema: { type: "object", properties: {}, required: [] },
+      },
+      {
+        name: "check_build_health",
+        description: "Runs typescript compiler checks to verify if the codebase currently has any type errors.",
+        inputSchema: { type: "object", properties: {}, required: [] },
+      }
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "get_drizzle_schema") {
+    try {
+      const schema = fs.readFileSync('./src/db/schema.ts', 'utf-8');
+      return { toolResult: schema };
+    } catch {
+      return { toolResult: "Schema file not found." };
+    }
+  }
+  
+  if (request.params.name === "check_build_health") {
+    try {
+      const output = execSync('npx tsc --noEmit', { encoding: 'utf-8' });
+      return { toolResult: output || "Build is perfectly healthy. No type errors." };
+    } catch (e: any) {
+      return { toolResult: \`Type errors detected:\\n\${e.stdout}\` };
+    }
+  }
+
+  throw new Error("Tool not found");
+});
+
+const transport = new StdioServerTransport();
+server.connect(transport).catch(console.error);
+`;

package/src/templates/stack.ts

@@ -0,0 +1,83 @@
+export const honoServerTemplate = `import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+import { z } from 'zod';
+import { db } from '../db';
+import { users } from '../db/schema';
+
+const app = new Hono().basePath('/api');
+
+// @ai-intent: STRICT ZOD VALIDATION REQUIRED FOR ALL ROUTES
+const createUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+const routes = app
+  .get('/users', async (c) => {
+    const allUsers = await db.select().from(users);
+    return c.json(allUsers);
+  })
+  .post('/users', zValidator('json', createUserSchema), async (c) => {
+    const { name, email } = c.req.valid('json');
+    const result = await db.insert(users).values({ name, email }).returning();
+    return c.json(result[0], 201);
+  });
+
+export type AppType = typeof routes;
+export default app;
+`;
+
+export const drizzleSchemaTemplate = `import { pgTable, text, serial, timestamp } from 'drizzle-orm/pg-core';
+
+// @ai-intent: SINGLE SOURCE OF TRUTH. Do not write raw SQL.
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  createdAt: timestamp('created_at').defaultNow(),
+});
+`;
+
+export const drizzleDbTemplate = `import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+
+const queryClient = postgres(process.env.DATABASE_URL || 'postgres://localhost:5432/nexus');
+export const db = drizzle(queryClient);
+`;
+
+export const nextjsPageTemplate = `import { hc } from 'hono/client';
+import { type AppType } from '../server';
+
+// @ai-intent: HONO RPC CLIENT INSTANTIATION
+// Agents MUST use this \`client\` to interact with the backend to preserve end-to-end type safety.
+const client = hc<AppType>('http://localhost:3000');
+
+export default async function Home() {
+  const res = await client.api.users.$get();
+  const users = await res.json();
+
+  return (
+    <main className="min-h-screen bg-black text-white p-24 font-sans">
+      <div className="max-w-xl mx-auto space-y-8">
+        <h1 className="text-4xl font-bold tracking-tight">Project Nexus 🧠</h1>
+        <p className="text-zinc-400">
+          Agent-Native Boilerplate initialized. Next.js, Hono, Drizzle, and Zod perfectly aligned.
+        </p>
+        
+        <div className="p-6 border border-zinc-800 rounded-lg bg-zinc-950">
+          <h2 className="text-xl font-semibold mb-4">Database Users</h2>
+          {users.length === 0 ? (
+            <p className="text-zinc-500">No users found. Try adding one via the API.</p>
+          ) : (
+            <ul className="space-y-2">
+              {users.map((u: any) => (
+                <li key={u.id} className="text-zinc-300">• {u.name} ({u.email})</li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </div>
+    </main>
+  );
+}
+`;

package/src/templates/twin.ts

@@ -0,0 +1,32 @@
+export const twinAppConceptsTemplate = `# CONCEPTS: Frontend (src/app)
+
+## Business Logic
+This directory contains the user-facing React application. It is responsible purely for data presentation and optimistic UI updates.
+
+## Boundaries
+- **DO NOT** perform direct database queries (Drizzle) from here.
+- **DO NOT** define raw Zod schemas for the database here.
+- **DO** use the generated Hono RPC client (e.g., \`hc\`) to communicate with the \`src/server\` API.
+- All components should default to React Server Components unless interactive hooks (useState, useEffect) are strictly required (use \`"use client"\`).
+`;
+
+export const twinServerConceptsTemplate = `# CONCEPTS: API Backend (src/server)
+
+## Business Logic
+This directory houses the Hono API routes. This is the exclusive gateway for all data mutations and retrievals.
+
+## Boundaries
+- **MUST** validate all incoming payloads using \`zValidator\` with Zod.
+- **MUST** export the \`AppType\` router type so the Next.js frontend can consume the RPC client with end-to-end type safety.
+- **DO NOT** import React or UI components into this layer.
+`;
+
+export const twinDbConceptsTemplate = `# CONCEPTS: Database Layer (src/db)
+
+## Business Logic
+This directory contains the single source of truth for the database schema using Drizzle ORM.
+
+## Boundaries
+- **MUST** export Drizzle Select/Insert schemas (e.g., \`createInsertSchema\`) using \`drizzle-zod\`.
+- This layer does not execute business logic; it strictly defines the schema shapes and relationships.
+`;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}