Craze-Data-check/AGENTS.md

AGENTS.md - Developer Guidelines for Craze-Data-check

Ruflo Standard Operating Procedure (SOP)

MANDATORY: Follow these steps for every user instruction.

1. Retrieve (Semantic Memory): Before starting, run ruflo memory search -q "<task description>" to find relevant historical patterns or previous solutions.
2. Verify (Security): Use ruflo security defend -i "<user instruction>" to ensure the instruction is safe and follows security protocols.
3. Execute (Agent Swarm): For complex tasks (refactors, multi-file changes), consider spawning specialized agents with ruflo agent spawn -t <type>.
4. Version Control: Use agentic-jujutsu for managing concurrent changes or if a lock-free approach is needed.
5. Record (Learning): After completion, record the outcome with ruflo memory store --key "<task_id>" --value "<outcome_details>" to improve future performance.

---

Build, Lint, and Test Commands

Development

npm run dev              # Start dev server on port 3000
npm run build            # Production build
npm run preview          # Preview production build
npm run clean            # Remove dist folder

Linting & Type Checking

npm run lint             # TypeScript type check only (tsc --noEmit)

Note: No test framework configured. To add tests, install Vitest or Jest.

---

Code Style Guidelines

General Principles

• Use TypeScript for all new code
• Prefer functional components with hooks over class components
• Keep components focused and modular
• Use meaningful variable and function names

Imports (order top to bottom)

1. React (react)
2. External libraries (lucide-react, xlsx, etc.)
3. Internal components (./components/...)
4. Internal lib/utils (./lib/...)
5. Types (./types)

import React, { useState, useMemo } from 'react';
import { Search, Filter, Edit2 } from 'lucide-react';
import { ExcelRow, COLUMNS } from '../types';
import { cn } from '../lib/utils';

TypeScript Conventions

• Use explicit types for props and function parameters
• Use any sparingly; prefer union types or interfaces
• Define column indices in a centralized COLUMNS object (see src/types.ts)

interface ProductDescriptionsProps {
  data: ExcelRow[];
  onEdit: (index: number) => void;
}

export const COLUMNS = {
  ARTICLE_NO: 0,
  ARTICLE_NAME: 2,
  LINE: 7,
};

Naming Conventions

Element	Convention	Example
Components	PascalCase	ProductDescriptions, MatrixView
Functions	camelCase	handleFileUpload, formatCellValue
Variables	camelCase	activeModule, paginatedData
Constants	UPPER_SNAKE_CASE	ARTICLE_NO, MAX_UPLOAD_SIZE
Interfaces	PascalCase	AppState, ExcelRow
Types	PascalCase	TabType, SortDirection

React Patterns

• Destructure props in function signature
• Use useMemo for expensive computations
• Use useCallback for event handlers passed to child components
• Keep useState calls at the top of component

Error Handling

• Use TypeScript's type system for runtime safety
• Use optional chaining (?.) and nullish coalescing (??)
• Validate file uploads with proper type checks

UI/Styling

• Use Tailwind CSS for all styling
• Use cn() utility from lib/utils for conditional classes
• Follow existing color scheme (slate, blue, green, red for status)
• Use lucide-react for icons

<button className={cn("px-4 py-2 rounded-md", isActive ? "bg-blue-600" : "bg-slate-800")}>

File Organization

src/
├── components/       # React components
├── lib/              # Utilities (utils.ts, auth.ts, supabase.ts)
├── services/         # External API integrations (gemini.ts, anthropic.ts)
├── types.ts          # TypeScript types and constants
├── App.tsx           # Main application
└── main.tsx          # Entry point

Data Processing

• Handle both string and number types when processing Excel data
• Use centralized column index constants
• Format numbers consistently (2 decimal places for prices/weights)
• Handle Excel date serial numbers properly

// Handle date columns from Excel
if (typeof val === 'number' && val >= 25569 && val <= 60000) {
  const excelEpoch = new Date(1899, 11, 30);
  return new Date(excelEpoch.getTime() + val * 86400000).toLocaleDateString('en-GB');
}

Git Workflow

• Make small, focused commits
• Write clear commit messages describing what changed
• Push to main to trigger Vercel deployment automatically

Environment Variables

• Use .env file for local development
• Never commit secrets - use Vercel dashboard for production env vars

Required: VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_GEMINI_API_KEY, VITE_ANTHROPIC_API_KEY