kaide 1.0.0

package/bin/kaide.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const command = process.argv[2];
+
+if (command !== "init") {
+  console.log("Usage: npx kaide init");
+  process.exit(1);
+}
+
+let createdCount = 0;
+let skippedCount = 0;
+
+async function copyDir(src, dest) {
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  await fs.mkdir(dest, { recursive: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+      continue;
+    }
+
+    try {
+      await fs.access(destPath);
+      skippedCount++;
+    } catch {
+      await fs.mkdir(path.dirname(destPath), { recursive: true });
+      await fs.copyFile(srcPath, destPath);
+      createdCount++;
+    }
+  }
+}
+
+async function main() {
+  const templateDir = path.resolve(__dirname, "../templates");
+  const targetDir = process.cwd();
+
+  try {
+    await fs.access(templateDir);
+    await copyDir(templateDir, targetDir);
+
+    console.log(`\n${createdCount} created • ${skippedCount} skipped`);
+    console.log("✅ Kaide is ready. Try: Ask AI to plan a new feature.");
+  } catch (err) {
+    console.error("CLI setup failed:", err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "kaide",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "kaide": "./bin/kaide.js"
+  }
+}

package/templates/.cursor/rules/core-principles.mdc

@@ -0,0 +1,54 @@
+---
+description: "USE WHEN: Applying core principles and enforcing global project constraints."
+alwaysApply: true
+---
+
+# Core Constitution
+
+## Constraints
+
+- **INTENTIONAL_TODO Rule:** Usage is ONLY permitted for non-functional placeholders (e.g., temporary mock UI, future logging). 
+- **Business Integrity:** Forbidden to use `INTENTIONAL_TODO` for business logic, error handling, or API integrations.
+- **Pseudo-code:** Forbidden. Provide working TypeScript/React code.
+- **Reference:** Do not say "Usually done like this"; link to repo rules.
+- **Validation:** Do not deliver without passing `pnpm check-types` and `pnpm lint`.
+- **Search First:** Analyze existing patterns before coding.
+- **Minimal Intervention:** Modify only necessary areas.
+- **Source of Truth:** Reference the codebase. Correct it if erroneous.
+- **Boy Scout:** Clean unused imports, `console.log`, and dead code.
+- **Naming:** `kebab-case` for folders/non-component files; `PascalCase` for React components.
+- **Exports:** Group exports with `index.ts`.
+- **No Silent Failures:** Do not swallow errors. Manage `try/catch` blocks.
+- **Secret Protection:** Do not log `.env` content.
+- **Dependency:** Obtain approval for new packages.
+
+## Bans
+
+- Comments (except JSDoc).
+- Placeholders/incomplete code.
+- `catch (e) {}` (Silent catch).
+- Logging secrets.
+- Out-of-scope refactoring.
+- `// ...existing code` (Provide full blocks).
+- Standard `TODO` or `FIXME` comments.
+- Using `INTENTIONAL_TODO` to skip core logic implementation.
+
+## Correct Implementation
+
+<example>
+```js
+try {
+  process(data);
+} catch (error) {
+  throw new ProcessingError({ cause: error });
+}
+```
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```js
+try { process(data); } catch (e) {}
+```
+</incorrect-example>

package/templates/.cursor/rules/frontend/api.mdc

@@ -0,0 +1,48 @@
+---
+description: "USE WHEN: Defining HTTP requests, endpoints, and handling API responses."
+globs: "src/lib/api.ts,src/features/**/api/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# API Layer
+
+## Constraints
+
+- **Location:** Place all HTTP calls under `features/[feature]/api`.
+- **Validation:** Use Zod for Input/Output validation.
+- **Return Type:** Return typed data, not raw responses.
+- **Error Handling:** Normalize API errors to `AppError` format.
+- **Config:** Load `baseURL` from env. Use a single `axios` instance (`src/lib/api.ts`).
+- **Interceptors:** Manage Auth, locale, and tenant logic in interceptors.
+- **Naming:** `verb-entity.api.ts` (e.g., `get-users.api.ts`). Function: `getUsers`.
+- **SSR Safety:** Use only whitelisted internal URLs or absolute paths for server-to-server calls to prevent SSRF.
+
+## Bans
+
+- `fetch`/`axios` inside UI components.
+- `axios.create` inside features.
+- Cross-feature API imports.
+- Using untyped responses.
+- Hardcoded endpoint strings in queries.
+- Throwing raw errors.
+- Leaking internal error stack traces to the client or API responses.
+- Constructing dynamic URLs using unsanitized user inputs.
+
+## Correct Implementation
+
+<example>
+```ts
+export const getUsers = async (): Promise<User[]> => {
+  const { data } = await api.get("/users");
+  return UserSchema.array().parse(data);
+};
+```
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```tsx
+useEffect(() => { axios.get("/users"); }, []);
+```
+</incorrect-example>

package/templates/.cursor/rules/frontend/forms.mdc

@@ -0,0 +1,45 @@
+---
+description: "USE WHEN: Constructing forms, validating inputs, and managing form state with Zod schemas."
+globs: "src/features/**/components/*Form*.tsx,src/features/**/schemas/*.ts"
+alwaysApply: false
+---
+
+# Form Management
+
+## Constraints
+
+- **Library:** Use `react-hook-form` + `@hookform/resolvers/zod`.
+- **Schema:** Store schemas in `features/[feature]/schemas/`.
+- **Defaults:** Define `defaultValues` fully using `z.infer` from the schema.
+- **Performance:** Use `useWatch` or `Controller` instead of `watch`.
+- **Submission:** Use `handleSubmit`. Prevent double clicks with `isSubmitting`.
+- **Errors:** Map server errors using `setError`.
+
+## Bans
+
+- Manually managing native `form` submit events.
+- Using `watch()` at the root level.
+- Synchronizing form state with `useEffect`.
+- Defining schemas inside component files.
+- Managing form inputs with `useState`.
+
+## Correct Implementation
+
+<example>
+```tsx
+const form = useForm<z.infer<typeof Schema>>({
+  resolver: zodResolver(Schema),
+  defaultValues: { email: "" }
+});
+const email = useWatch({ control: form.control, name: "email" });
+```
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```tsx
+const [email, setEmail] = useState("");
+const values = form.watch(); // Root watch
+```
+</incorrect-example>

package/templates/.cursor/rules/frontend/i18n.mdc

@@ -0,0 +1,41 @@
+---
+description: "USE WHEN: Managing translation files (JSON), localization keys, or implementing multi-language logic."
+globs: "src/messages/**/*.json,src/i18n/**/*.{ts,tsx},src/features/**"
+alwaysApply: false
+---
+
+# Internationalization (i18n)
+
+## Constraints
+
+- **Library Selection:** Delegate specific hook/method usage to the framework constitution (`nextjs.mdc` or `tanstack-start.mdc`).
+- **Keys:** Use flat or max 3-level deep JSON structures. Use `camelCase` for keys.
+- **SSOT:** All translation keys MUST be defined in `src/messages/`.
+- **Type Safety:** Use the library's native type-generation features. Magic strings for keys are forbidden.
+- **Namespacing:** Use namespaces for features (e.g., `auth.login`, `profile.settings`) to maintain modularity.
+
+## Bans
+
+- Hardcoded strings in UI components.
+- Dynamic key construction (e.g., `t("prefix." + variable)`).
+- Reading locale via `window.location` or manual URL parsing.
+- JSON hierarchy deeper than 3 levels.
+- Async translation loading that causes layout shifts.
+
+## Correct Implementation
+
+<example>
+// Common Pattern (Usage details delegated to framework MDC)
+const t = useTranslations("auth");
+return <button>{t("loginButton")}</button>;
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+// BAN: Hardcoded string
+return <button>Login</button>;
+
+// BAN: Dynamic key generation
+const label = t("welcome_" + type);
+</incorrect-example>

package/templates/.cursor/rules/frontend/nextjs.mdc

@@ -0,0 +1,91 @@
+---
+description: Next.js 16 App Router Standards & Constraints
+globs: src/app/**/{page,layout,loading,error,not-found}.tsx
+alwaysApply: false
+---
+# Next.js 16 App Router Constitution
+
+## Constraints
+
+- **Server-First Architecture:** All components in `src/app` MUST be Server Components (RSC) by default.
+- **Client Component Usage:** The `"use client"` directive is strictly limited to leaf-node components that require interactivity (hooks, events) or Browser APIs.
+- **Feature Delegation:** `src/app` is strictly for routing/layout. All business logic, UI components, and domain hooks MUST reside in `src/features`.
+- **Server Actions:** All mutations MUST use Server Actions defined in dedicated `actions.ts` files within `src/features`. Actions MUST call the API layer only; direct database access inside actions is forbidden.
+- **i18n Implementation:** Use `next-intl` for translations. Follow the patterns defined in `i18n.mdc`.
+- **Metadata:** SEO metadata MUST be defined using the Metadata API in `page.tsx` or `layout.tsx`.
+- **Streaming:** Use `loading.tsx` for route-level async states. Use `<Suspense>` for granular feature-level hydration.
+- **CSRF Protection:** Verify Origin/Referer headers in Server Actions. Use `action.bind` to lock sensitive IDs on the server-side.
+- **Secret Isolation:** Use the `server-only` package in API and database files to prevent accidental leakage to the client.
+
+## Bans
+
+- **Inline Server Actions:** Defining Server Actions inside components or pages is FORBIDDEN.
+- **Client-Side Data Fetching in Effects:** Using `useEffect` for data fetching is FORBIDDEN. Use TanStack Query or RSC.
+- **Logic in Route Files:** Implementing complex logic directly in `page.tsx` or `layout.tsx` is FORBIDDEN.
+- **Manual Head Management:** Using `head.tsx` or manual `<meta>` tags is FORBIDDEN.
+- **"use client" at Root:** Marking `page.tsx` or `layout.tsx` as `"use client"` is FORBIDDEN. Wrap interactive logic in feature components instead.
+- **Raw Serialization:** Forbidden to pass raw database models or sensitive user data directly from RSC to Client Components.
+
+## Correct Implementation
+
+<example>
+// src/app/dashboard/page.tsx
+import { DashboardFeature } from "@/features/dashboard";
+import { getDashboardData } from "@/features/dashboard/api";
+import { getTranslations } from "next-intl/server";
+
+export async function generateMetadata() {
+  const t = await getTranslations("dashboard");
+  return { title: t("title") };
+}
+
+export default async function DashboardPage() {
+  const data = await getDashboardData();
+
+  return (
+    <main>
+      <DashboardFeature initialData={data} />
+    </main>
+  );
+}
+</example>
+
+<example>
+// src/features/auth/actions/login.ts
+"use server";
+
+import { loginSchema } from "../schemas/login-schema";
+import { api } from "@/lib/api";
+
+export async function loginAction(formData: FormData) {
+  const validated = loginSchema.parse(Object.fromEntries(formData));
+  return await api.post("/auth/login", validated);
+}
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+// BAN: "use client" on page level and useEffect fetching
+"use client"; 
+
+export default function Page() {
+  const [data, setData] = useState(null);
+  useEffect(() => {
+    fetch("/api/data").then(res => res.json()).then(setData);
+  }, []);
+
+  return <div>{data?.name}</div>;
+}
+</incorrect-example>
+
+<incorrect-example>
+// BAN: Inline server action
+export default function Form() {
+  async function handle() {
+    "use server";
+    // database call
+  }
+  return <form action={handle}>...</form>;
+}
+</incorrect-example>

package/templates/.cursor/rules/frontend/performance.mdc

@@ -0,0 +1,61 @@
+---
+description: "USE WHEN: Optimizing Core Web Vitals, managing assets, and ensuring high Lighthouse/A11y scores."
+globs: "src/app/**/*.{ts,tsx},src/routes/**/*.{ts,tsx},src/components/**/*.{ts,tsx},src/features/**/components/**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# Performance & Accessibility (Lighthouse 95+)
+
+## Constraints
+
+- **LCP Optimization:** Use `priority` attribute for the first visible `Image` (Next.js) or hero assets.
+- **Image Standards:** Always use `next/image` or framework-specific optimized loaders. Define explicit `width` and `height` to prevent CLS.
+- **Icon Strategy:** Use tree-shakable icons (e.g., `lucide-react`). Forbidden to import entire libraries.
+- **Font Loading:** Use `swap` display strategy. Optimize via `next/font` or local self-hosting.
+- **A11y SSOT:** All interactive elements MUST have `aria-label`, `role`, or associated `<label>`.
+- **Contrast:** Maintain WCAG AA compliance (4.5:1 ratio).
+- **Bundle Size:** Keep feature chunks <50kb. Use dynamic imports for heavy components (charts, editors).
+- **Asset Links:** Ref: `ui-components.mdc` for Skeleton/CLS rules.
+
+## Bans
+
+- **Layout Shift:** Forbidden to render content without reserved dimensions (use Skeletons).
+- **Native Img:** Forbidden to use raw `<img>` tags.
+- **Blocking JS:** Forbidden to use heavy 3rd party scripts in the main thread (use `next/script` or Web Workers).
+- **A11y Gaps:** Forbidden to use `div` as a button without `tabIndex` and `onKeyDown`.
+- **Alt Text:** Forbidden to leave `alt` attributes empty or generic (e.g., "image").
+
+## Correct Implementation
+
+<example>
+// Optimized LCP and A11y
+import Image from "next/image";
+
+export const Hero = () => (
+  <section>
+    <h1>{t("title")}</h1>
+    <Image 
+      src="/hero.webp" 
+      alt="Dashboard analytics overview" 
+      width={1200} 
+      height={600} 
+      priority 
+    />
+    <button aria-label="Start free trial" onClick={handleAction}>
+      {t("cta")}
+    </button>
+  </section>
+);
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+// BAN: Native img, no dimensions, no priority, no aria-label
+const BadHero = () => (
+  <div>
+    <img src="/hero.png" />
+    <div onClick={handleAction}>Click here</div>
+  </div>
+);
+</incorrect-example>

package/templates/.cursor/rules/frontend/react-best-practices.mdc

@@ -0,0 +1,45 @@
+---
+description: "USE WHEN: Designing React components, implementing hooks, and managing component lifecycles."
+globs: "src/components/**/*.{ts,tsx},src/hooks/**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# React Best Practices
+
+## Constraints
+
+- **SRP:** Keep components small (max 150 lines).
+- **Composition:** Use `children` or `slots` instead of prop drilling.
+- **Naming:** Use `PascalCase` for components, `useCamelCase` for hooks.
+- **Hooks:** Move business logic to custom hooks.
+- **State:** Lift state to the nearest common ancestor.
+- **Updates:** Use `setState(prev => ...)` for state updates.
+- **Effects:** Use `useEffect` as a last resort. Prefer event handlers or `useMemo`.
+- **Keys:** Use stable IDs for lists (index is forbidden).
+
+## Bans
+
+- Prop drilling (>2 levels).
+- Class components.
+- Incomplete dependency arrays.
+- Syncing props to state (use Derived state).
+- Heavy computations during render.
+- Data fetching inside components (violation of API rules).
+
+## Correct Implementation
+
+<example>
+```tsx
+const stableHandler = useEvent(handler);
+useEffect(() => { stableHandler(data); }, [data]);
+```
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```tsx
+useEffect(() => { fetchData(); }, []); // Fetching forbidden
+useEffect(() => { setVal(props.val); }, [props.val]); // Sync forbidden
+```
+</incorrect-example>

package/templates/.cursor/rules/frontend/state-management.mdc

@@ -0,0 +1,42 @@
+---
+description: "USE WHEN: Managing global client state with Zustand and handling client-side state logic."
+globs: "src/stores/**/*.ts,src/features/**/stores/**/*.ts"
+alwaysApply: false
+---
+
+# State Management
+
+## Constraints
+
+- **Library:** Use `Zustand` for client state.
+- **Scope:** Define Global state in `src/stores`, Feature state in `src/features/[feature]/stores`.
+- **Selectors:** Always consume state via selectors (`useStore(s => s.val)`).
+- **SSR:** Guarantee client-side rendering with `useHydrated`.
+- **Persistence:** Configure `onRehydrateStorage` when using `persist` middleware.
+- **Server State:** Use TanStack Query. Do not store server data in the global store.
+
+## Bans
+
+- Passing store data via props.
+- Storing high-frequency state (e.g., inputs) in the store.
+- Executing side-effects (API calls) inside the store.
+- Accessing `window`/`localStorage` during initialization.
+- Returning the entire store without selectors.
+
+## Correct Implementation
+
+<example>
+```ts
+const user = useUserStore((s) => s.user);
+const isHydrated = useHydrated();
+```
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```ts
+const { user } = useUserStore(); // Missing selector
+const store = create(() => ({ data: localStorage.getItem("x") })); // SSR Error
+```
+</incorrect-example>

package/templates/.cursor/rules/frontend/tanstack-query.mdc

@@ -0,0 +1,51 @@
+---
+description: "USE WHEN: Managing server state, fetching data, and handling mutations with TanStack Query."
+globs: "src/features/**/api/*.{ts,tsx},src/features/**/hooks/*.{ts,tsx},src/providers/query-provider.tsx"
+alwaysApply: false
+---
+
+# TanStack Query
+
+## Constraints
+
+- **Structure:** Use Query Key Factory (`src/features/[feature]/api/query-keys.ts`).
+- **Hooks:** Create custom hooks for every query/mutation.
+- **Keys:** Use `as const`. Establish hierarchical structure (all -> lists -> details).
+- **Signal:** Pass `AbortSignal` to the API function.
+- **Invalidation:** Invalidate relevant keys in mutation `onSuccess`.
+- **Pagination:** Include `page` and filters in the query key.
+
+## Bans
+
+- `useQuery` inside components (Custom hooks are mandatory).
+- Manual string query keys.
+- Using API responses without validation.
+- Ignoring Loading/Error states.
+
+## Correct Implementation
+
+<example>
+// features/skills/api/query-keys.ts
+export const skillKeys = {
+  all: ['skills'] as const,
+  lists: () => [...skillKeys.all, 'list'] as const,
+  list: (filters: object) => [...skillKeys.lists(), { filters }] as const,
+  details: () => [...skillKeys.all, 'detail'] as const,
+  detail: (id: string) => [...skillKeys.details(), id] as const,
+};
+
+// features/skills/hooks/use-get-skills.ts
+export const useGetSkills = (filters: object) =>
+  useQuery({
+    queryKey: skillKeys.list(filters),
+    queryFn: ({ signal }) => getSkills(filters, signal),
+  });
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```tsx
+useQuery({ queryKey: ["posts"], queryFn: () => axios.get("/posts") });
+```
+</incorrect-example>

package/templates/.cursor/rules/frontend/tanstack-start.mdc

@@ -0,0 +1,85 @@
+---
+description: TanStack Start Routing, Loaders, and Server Functions Standards
+globs: src/routes/**/*.{ts,tsx}
+alwaysApply: false
+---
+# TanStack Start Constitution
+
+## Constraints
+
+- **Route Definition:** Always use `createFileRoute`. Path MUST strictly match the file system location.
+- **Component Scope:** Keep route files thin. Only orchestrate routing and data. Move UI and business logic to `src/features`.
+- **Data Loading:** Fetch all route-level data in `loader`. Consume via `Route.useLoaderData` or `useSuspenseQuery`.
+- **Guards:** Put auth, redirects, and preconditions in `beforeLoad`.
+- **Hydration:** For Next.js RSC, use dehydrate(queryClient) pattern. For Start, use loader prefetching.
+- **Server Functions:** Wrap all backend-only logic in standalone `serverFn`. Functions MUST act as a bridge to the API layer; keep database orchestration and business logic inside src/features/api or helpers.
+- **Search Params:** Validate all search params with `validateSearch` using a Zod schema. Never trust raw search values.
+- **i18n Implementation:** Use `paraglide-js` for translations. Import messages from `@/paraglide/messages`.
+- **Error Handling:** Provide `errorComponent` for failure states. Handle expected errors in the loader.
+- **Loading UI:** Provide `pendingComponent` for async states when needed.
+- **Not Found:** Provide `notFoundComponent` for missing resources.
+- **Head/SEO:** Define metadata with the `head` property. Keep it deterministic and typed.
+- **Sync:** Ensure route paths are kept in sync via `tsr watch` command.
+- **Guard Security:** Enforce session and permission checks within `beforeLoad` or dedicated middleware before `serverFn` execution.
+
+## Bans
+
+- **Client-Side Fetching:** Fetching data inside the component body via `useEffect` or `useQuery` (without loader prefetch) is FORBIDDEN.
+- **Inline serverFn:** Defining `serverFn` inside a component or route definition is FORBIDDEN. They MUST be exported as standalone constants.
+- **Next.js Conventions:** Using `"use server"` directives, `page.tsx` naming, or Next.js-specific hooks (`useRouter` from next/navigation) is STRICTLY FORBIDDEN.
+- **Untyped Routes:** Navigating via string paths without type-safety (using `Link` or `Maps` without the `to` property pointing to a valid route) is FORBIDDEN.
+- **Insecure Env Vars:** Forbidden to store secrets or private keys in environment variables with `VITE_` prefixes.
+
+## Correct Implementation
+
+<example>
+// src/routes/posts/$postId.tsx
+import { createFileRoute } from '@tanstack/react-router';
+import { PostFeature } from '@/features/posts';
+import { getPostById } from '@/features/posts/api';
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: ({ params }) => getPostById(params.postId),
+  component: PostPage,
+});
+
+function PostPage() {
+  const post = Route.useLoaderData();
+  return <PostFeature post={post} />;
+}
+</example>
+
+<example>
+// src/features/auth/api/auth-actions.ts (Standalone serverFn)
+import { createServerFn } from '@tanstack/start';
+import { z } from 'zod';
+
+export const loginFn = createServerFn({ method: 'POST' })
+  .validator(z.object({ email: z.string().email() }))
+  .handler(async ({ data }) => {
+    // Server-side logic here
+    return { success: true };
+  });
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+// BAN: Data fetching inside component without loader
+export const Route = createFileRoute('/dashboard')({
+  component: () => {
+    const { data } = useQuery({ queryKey: ['dash'], queryFn: fetchDash }); 
+    return <div>{data.name}</div>;
+  }
+});
+</incorrect-example>
+
+<incorrect-example>
+// BAN: Inline Next.js style server action
+export const Route = createFileRoute('/login')({
+  component: () => {
+    async function action() { "use server"; ... } 
+    return <form action={action}>...</form>;
+  }
+});
+</incorrect-example>

package/templates/.cursor/rules/frontend/testing.mdc

@@ -0,0 +1,27 @@
+---
+description: "USE WHEN: Writing unit, integration, or component tests. Mandatory for logic in features."
+globs: "**/*.{test,spec}.{ts,tsx}"
+alwaysApply: false
+---
+
+# Testing Guide (Pragmatic)
+
+## Principles
+- **Value over Coverage:** Focus on testing complex business logic in `features/logic`. Skip simple UI components unless critical.
+- [cite_start]**Behavior Testing:** Focus on user outcomes (Arrange-Act-Assert)[cite: 3].
+
+## Tech Stack
+- [cite_start]Vitest & React Testing Library[cite: 1, 12].
+
+## Preferences (Not Hard Rules)
+- [cite_start]**API:** Use `MSW` for stable features; simple mocks are okay for rapid prototyping[cite: 5, 8].
+- [cite_start]**Location:** Keep `.test.ts` next to implementation[cite: 4].
+- [cite_start]**Snapshots:** Use only for small, static data structures to prevent maintenance hell.
+
+## Correct Approach
+<example>
+it('should calculate discount correctly', () => {
+  const result = calculateTotal({ price: 100, discount: 20 }); 
+  expect(result).toBe(80); 
+});
+</example>

package/templates/.cursor/rules/frontend/typescript.mdc

@@ -0,0 +1,46 @@
+---
+description: "USE WHEN: Defining TypeScript types, Zod schemas, and generic constraints for type safety."
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# TypeScript
+
+## Constraints
+
+- **Zod-First:** Write Zod schemas for API/Domain contracts. Derive types via `z.infer`.
+- **Strict:** Operate in `strict: true` mode.
+- **Arrays:** Use `T[]`. Use `Array<T>` only for nested types.
+- **Enums:** Use `z.enum` or `as const` objects. Native `enum` is forbidden.
+- **Immutability:** Use `readonly` or `as const`.
+- **Return Types:** Explicitly define return types for exported functions.
+- **Generics:** Use constraints (`T extends object`).
+
+## Bans
+
+- `any`.
+- `as Type` (except in tests).
+- `!` (Non-null assertion).
+- Using Interface and Type simultaneously.
+- `I` or `T` prefixes (`IUser`).
+- Type soup (`Pick<Omit<Partial<...>>>`).
+- Type soup (Pick<Omit<Partial<...>>> nesting > 2). 
+  Exception: Deriving Form schemas from API schemas using Zod's `.pick()`, `.omit()`, or `.extend()` is encouraged to maintain SSOT.
+
+## Correct Implementation
+
+<example>
+```ts
+const UserSchema = z.object({ id: z.string() });
+type User = z.infer<typeof UserSchema>;
+```
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```ts
+interface IUser { id: any; }
+const user = data as User;
+```
+</incorrect-example>

package/templates/.cursor/rules/frontend/ui-components.mdc

@@ -0,0 +1,46 @@
+---
+description: "USE WHEN: Building UI components, structuring layouts, and applying styles using Tailwind CSS."
+globs: "src/components/**/*.{ts,tsx},src/features/**/components/**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# UI Components
+
+## Constraints
+
+- **Hierarchy:** Organize by `ui` (stateless), `shared` (common), and `feature` (domain logic).
+- **Atomic:** Keep `src/components/ui` pure; forbid API/Store dependencies.
+- **Styling:** Use Tailwind CSS and `cn()`. Use Tokens instead of Hex/RGB values.
+- **Responsiveness:** Design mobile-first (e.g., `p-4 md:p-8`).
+- **Loading:** Use Skeletons matching actual dimensions to prevent CLS.
+- **A11y:** Enforce semantic HTML and `aria` attributes.
+- **Exports:** Use Named exports only.
+
+## Bans
+
+- Inline styles.
+- CSS Modules / styled-components.
+- Hex/RGB color usage (use Tokens).
+- Default exports.
+- Data fetching inside atomic components.
+- `div` soup (use Semantic tags).
+
+## Correct Implementation
+
+<example>
+```tsx
+export const ProfileCard = ({ name }: { name: string }) => (
+  <div className={cn("p-4", "bg-muted")}>{name}</div>
+);
+```
+</example>
+
+## Incorrect Implementation
+
+<incorrect-example>
+```tsx
+export default function Button() {
+  return <div style={{ color: "red" }}>Click</div>;
+}
+```
+</incorrect-example>

package/templates/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Persona
+Frontend Architect specialized in Next.js 16 and TanStack Start. Decisions: SOLID, SRP, end-to-end type-safety. Approach: Plan-first.
+
+## CLI Commands
+- **Dev:** `pnpm install && pnpm dev`
+- **Validation:** `pnpm lint && pnpm check-types`
+- **Build:** `pnpm build`
+
+## Operational Guardrails
+- **Planning Protocol:** Approval required for: Boundaries, Routing/Rendering, State, Schemas, New Dependencies, Infrastructure.
+- **Context Integrity:** Read `.mdc` files. No hallucinations for unknown paths; ask or state UNKNOWN.
+
+## Communication
+- **Language:** Chat: Turkish. Code/Types/Naming: English.
+- **Self-Documentation:** JSDoc for complex logic as per `.mdc` standards.
+
+## Resource Map (Progressive Disclosure)
+- `.cursor/rules/core-principles.mdc` (Global Rules)
+- `.cursor/rules/frontend/*.mdc` (Technical Implementation)
+- `docs/architecture-guide.md` (System Design)
+- `docs/MEMORIES.md` (Project Context)

package/templates/docs/MEMORIES.md

@@ -0,0 +1,13 @@
+# Project Memories & Context
+
+This file serves as a persistent memory bank for the project. It documents key decisions, context, and evolution of the codebase that might not be obvious from the code itself.
+
+## Context
+- **Project Goal:** [Brief description of what this project does]
+- **Core Domain:** [Main business domain]
+
+## Key Decisions
+- [Date] - [Decision Title]: [Description of why a certain technical choice was made]
+
+## Evolution
+- [Date] - [Milestone]: [Description of major changes or milestones reached]

package/templates/docs/architecture-guide.md

@@ -0,0 +1,100 @@
+# Architecture Constitution
+
+## Technical Stack (SSOT)
+
+| Layer | Technology | Authority (Rule Ref) |
+| :--- | :--- | :--- |
+| **Server State** | TanStack Query | `tanstack-query.mdc` |
+| **Client State** | Zustand | `state-management.mdc` |
+| **Validation** | Zod | `typescript.mdc` |
+| **UI / Styling** | shadcn/ui + Tailwind | `ui-components.mdc` |
+| **API Client** | Axios (Centralized) | `api.mdc` |
+
+## Framework Isolation Boundary
+
+Implementation details for Next.js and TanStack Start are strictly segregated. Framework-specific patterns are delegated to their respective .mdc rules.
+
+- **Next.js 16:** See `.cursor/rules/frontend/nextjs.mdc`
+- **TanStack Start:** See `.cursor/rules/frontend/tanstack-start.mdc`
+
+**Shared Layer:** Reserved strictly for framework-agnostic code (`shared/schemas`, `ui-primitives`).
+
+## Global Directory Hierarchy
+
+Adhere strictly to the following tree structure. Creating arbitrary folders is FORBIDDEN:
+
+```text
+src/
+├── app/ | routes/        # Routing layer (See Framework Rules)
+├── features/             # Domain & business logic
+│   └── [feature-name]/
+│       ├── api/
+│       ├── components/
+│       ├── helpers/
+│       ├── hooks/
+│       ├── schemas/
+│       ├── stores/
+│       ├── types/
+│       └── index.ts
+├── components/
+│   ├── ui/               # Atomic (shadcn)
+│   ├── layout/           # Layout parts
+│   └── shared/           # Reusable functional
+├── config/               # App/SEO config
+├── constants/            # Static values
+├── helpers/              # Framework-agnostic pure functions
+├── hooks/
+├── i18n/                 # Localization setup
+├── lib/                  # Third-party configurations
+├── messages/             # Translations
+├── providers/            # Global context
+├── schemas/              # Shared validation
+├── stores/               # Global state
+├── styles/               # Tailwind/base CSS
+├── types/                # Global TS types
+└── env.ts                # Env validation
+```
+
+## Shared vs. Feature Matrix (The Rule of Three)
+
+Apply the following metric hierarchy to determine code location:
+
+- **Default Scope:** All logic and components originate within `features/[feature]/`.
+- **Promotion:** Any logic or component requested by 2 different features MUST be moved to the global `src/` (shared) layer.
+- **Cross-Import Ban:** Direct imports between features are FORBIDDEN. Communication is restricted to the `src/shared` layer or via prop-drilling at the Page level.
+- **Helpers:** Pure TypeScript functions that strictly transform input to output without side effects.
+- **Lib:** Contains project-specific configured instances of external libraries. Components MUST import the wrapped instance from `src/lib` rather than the external package directly.
+- **Zod Schemas:** All feature-related schemas MUST be stored in `features/[feature]/schemas/`. API functions and UI components MUST import from this single source to prevent duplication.
+
+## Server State & Ownership
+
+Server state is global, but access is hierarchical:
+
+- **Ownership:** Every API hook belongs to its respective feature. Promote to `src/hooks/api` only if shared.
+- **Invalidation:** Cross-feature cache invalidation is permitted only via the global `Query Key Factory`.
+- **Defaults:** StaleTime: ~60s (Lists), ~5m (Details). Centralized management: `src/providers/query-provider.tsx`.
+
+## Rendering & Access Control
+
+Rendering strategies (RSC vs Client) and Data Fetching patterns are governed by the active framework's specific rule file.
+
+- **No HTTP in UI:** UI layer is FORBIDDEN from using `axios` or `fetch` directly. Consume only `features/api` functions.
+- **Insecure Scripts:** All content MUST adhere to the project's Content Security Policy; `unsafe-inline` and `unsafe-eval` are strictly forbidden.
+
+## Canonical Rules (MDC Refs)
+
+This document is the architectural map. Enforceable laws are located in:
+
+- `Ref: .cursor/rules/core-principles.mdc`
+- `Ref: .cursor/rules/frontend/api.mdc`
+- `Ref: .cursor/rules/frontend/forms.mdc`
+- `Ref: .cursor/rules/frontend/i18n.mdc`
+- `Ref: .cursor/rules/frontend/nextjs.mdc`
+- `Ref: .cursor/rules/frontend/performance.mdc`
+- `Ref: .cursor/rules/frontend/react-best-practices.mdc`
+- `Ref: .cursor/rules/frontend/state-management.mdc`
+- `Ref: .cursor/rules/frontend/tanstack-query.mdc`
+- `Ref: .cursor/rules/frontend/tanstack-start.mdc`
+- `Ref: .cursor/rules/frontend/testing.mdc`
+- `Ref: .cursor/rules/frontend/typescript.mdc`
+- `Ref: .cursor/rules/frontend/ui-components.mdc`