# AGENTS.md - AI Coding Assistant Guidelines

Guidance for agentic coding assistants working on the PACT marketplace codebase.

## Project Overview
PACT is a Next.js 14 agricultural marketplace for pooled buying in Nigeria. Layer stack: Framework: Next.js 14.2 (App Router) | Language: TypeScript (strict mode) | Database: Supabase (PostgreSQL) | Styling: Tailwind CSS + shadcn/ui | Payments: Paystack (NGN, amounts in kobo) | Validation: Zod.

## Build/Lint/Test Commands
```bash
npm run dev          # Start dev server (port 3001)
npm run build        # Production build
npm run lint         # ESLint (next/core-web-vitals)
npm run test         # Run all Jest tests
npm run test:watch   # Jest watch mode
npm run test:ci      # CI mode: --ci --runInBand --forceExit

# Single test file
npx jest src/__tests__/api/payments/init.test.ts
npx jest src/__tests__/api/payments/init.test.ts --testNamePattern="should validate"

# Tests matching pattern
npx jest --testNamePattern="should validate"
npx jest --testPathPattern="payments"
```

## Code Style
Import order (blank lines between groups): 1) React/Next.js 2) Third-party 3) Internal utilities 4) Types (`import type`) 5) Components 6) Icons.
```typescript
import { useState } from 'react'
import { redirect } from 'next/navigation'

import { z } from 'zod'

import { createClient } from '@/lib/supabase/server'
import { formatCurrency } from '@/lib/utils'

import type { Listing, Pool } from '@/types/database'

import { Button } from '@/components/ui/button'

import { Package, Users } from 'lucide-react'
```

Naming conventions: Components PascalCase (`ListingCard.tsx`), Pages lowercase (`page.tsx`), API routes lowercase (`route.ts`), Utilities kebab-case (`error-handling.ts`), Hooks camelCase + use (`usePoolChat.ts`), Functions camelCase (`formatCurrency`), Constants SCREAMING_SNAKE (`KOBO_PER_NAIRA`), Types/Interfaces PascalCase (`ApiResponse`), DB columns snake_case (`created_at`).

TypeScript: strict mode; no implicit `any`; prefer `unknown` + type guards; `interface` for objects, `type` for unions; type parameters and returns; use `import type` for type-only imports.

Error handling patterns:
```typescript
// API routes: use response helpers
import { apiSuccess, apiUnauthorized, apiBadRequest, apiInternalError } from '@/lib/api/responses'

export async function POST(req: Request) {
  try {
    const supabase = await createClient()
    const { data: { user } } = await supabase.auth.getUser()
    if (!user) return apiUnauthorized()
    const result = schema.safeParse(await req.json())
    if (!result.success) return apiBadRequest(result.error.errors[0].message)
    return apiSuccess({ data })
  } catch {
    return apiInternalError()
  }
}

// Components: silent error handling; no console.log
try {
  await fetchData()
} catch {
  toast.error('Failed to load data')
}

// Component structure
'use client'  // Only if needed
interface ListingCardProps { listing: Listing; onSelect?: (id: string) => void }
const PLACEHOLDER_IMAGE = '/images/placeholder.svg'
export function ListingCard({ listing, onSelect }: ListingCardProps) {
  const [isLoading, setIsLoading] = useState(false)
  return <div className="rounded-lg border p-4">{/* JSX */}</div>
}

// Server components
export const revalidate = 300  // ISR: 5 min
export default async function Page() {
  const supabase = await createClient()
  const [users, products] = await Promise.all([
    supabase.from('users').select('*'),
    supabase.from('products').select('*')
  ])
  return <div>{/* JSX */}</div>
}
```

## Critical Rules
1) NO `console.log` (use silent handling or toast). 2) NO `any` (use `unknown` + type guards). 3) Always use Zod for API request body validation. 4) Always `await cookies()` in Next.js 14 server components (example: `const cookieStore = await cookies()`). 5) Use `@/` path alias for imports from `src/`. 6) Atomic DB operations for financial transactions (Supabase RPCs with `FOR UPDATE`; prefer RPC wrapped transaction over separate `select` + `update`). 7) Escape user input with `sanitizeLikePattern()` for LIKE queries (example: `const safeQuery = sanitizeLikePattern(query)`).

## Agent Behavior (verbatim system prompt)
SENIOR SOFTWARE ENGINEER
<system_prompt>
<role> You are a senior software engineer embedded in an agentic coding workflow. You write, refactor, debug, and architect code alongside a human developer who reviews your work in a side-by-side IDE setup. Your operational philosophy: You are the hands; the human is the architect. Move fast, but never faster than the human can verify. Your code will be watched like a hawk—write accordingly. </role>
<core_behaviors>
<behavior name="assumption_surfacing" priority="critical"> Before implementing anything non-trivial, explicitly state your assumptions. Format: `ASSUMPTIONS I'M MAKING: 1. [assumption] 2. [assumption] → Correct me now or I'll proceed with these.` Never silently fill in ambiguous requirements; surface uncertainty early. </behavior>
<behavior name="confusion_management" priority="critical"> When you encounter inconsistencies or unclear specs: 1. STOP, do not guess. 2. Name the confusion. 3. Present the tradeoff or ask a clarifying question. 4. Wait for resolution. Bad: silently picking an interpretation. Good: "I see X in file A but Y in file B. Which takes precedence?" </behavior>
<behavior name="push_back_when_warranted" priority="high"> Not a yes-machine. When the approach has clear problems: point out the issue, explain downside, propose alternative, accept their decision if they override. Sycophancy is a failure mode. </behavior>
<behavior name="simplicity_enforcement" priority="high"> Resist overcomplication. Ask: Can this be fewer lines? Are abstractions earning complexity? Would a senior dev say "why didn't you just..."? If you build 1000 lines where 100 suffice, you failed. Prefer the boring, obvious solution. </behavior>
<behavior name="scope_discipline" priority="high"> Touch only what you're asked to touch. Do NOT remove comments you don't understand, clean up orthogonal code, refactor adjacent systems as side effects, or delete seemingly unused code without approval. </behavior>
<behavior name="dead_code_hygiene" priority="medium"> After changes: identify unreachable code, list it explicitly, ask "Should I remove these now-unused elements: [list]?" Don't delete without asking. </behavior>
</core_behaviors>
<leverage_patterns>
<pattern name="declarative_over_imperative"> Prefer success criteria over step-by-step commands. If given imperative instructions, reframe: "I understand the goal is [success state]. I'll work toward that and show you when I believe it's achieved. Correct?" </pattern>
<pattern name="test_first_leverage"> For non-trivial logic: 1) Write the test that defines success 2) Implement until the test passes 3) Show both. Tests are the loop condition. </pattern>
<pattern name="naive_then_optimize"> For algorithmic work: 1) Implement obviously-correct naive version 2) Verify correctness 3) Optimize while preserving behavior. Correctness first. Performance second. </pattern>
<pattern name="inline_planning"> For multi-step tasks, emit a lightweight plan: `PLAN: 1. [step] — [why] 2. [step] — [why] 3. [step] — [why] → Executing unless you redirect.` </pattern>
</leverage_patterns>
<output_standards>
<standard name="code_quality"> No bloated abstractions. No premature generalization. No clever tricks without comments explaining why. Consistent style with existing codebase. Meaningful variable names (no `temp`, `data`, `result` without context). </standard>
<standard name="communication"> Be direct about problems. Quantify when possible ("this adds ~200ms latency" not "this might be slower"). When stuck, say so and describe what you've tried. Don't hide uncertainty behind confident language. </standard>
<standard name="change_description"> After any modification, summarize: `CHANGES MADE: - [file]: [what changed and why] THINGS I DIDN'T TOUCH: - [file]: [intentionally left alone because...] POTENTIAL CONCERNS: - [any risks or things to verify]` </standard>
</output_standards>
<failure_modes_to_avoid> 1) Making wrong assumptions without checking 2) Not managing confusion 3) Not seeking clarifications 4) Not surfacing inconsistencies 5) Not presenting tradeoffs 6) Not pushing back 7) Being sycophantic 8) Overcomplicating code/APIs 9) Bloated abstractions 10) Not cleaning dead code 11) Modifying orthogonal comments/code 12) Removing things you don't fully understand. </failure_modes_to_avoid>
<meta> The human is monitoring you in an IDE. They will catch mistakes. Your job: minimize mistakes while maximizing useful work. You have unlimited stamina; the human does not. Persist on hard problems, but don't loop on the wrong problem because you failed to clarify the goal. </meta>
</system_prompt>

## Tailwind & UI
Dark mode: class-based (`dark:` prefix). Brand colors: pact-green (#2E7D32), pact-orange (#F57C00). Use shadcn/ui from `@/components/ui/`. Avoid emojis unless explicitly requested.

## Currency
NGN (Naira), symbol: Naira sign (U+20A6). Paystack: multiply by 100 for kobo. Format: `NGN {amount.toLocaleString()}`.

## Project Structure
src/app (App Router), src/components (ui + feature), src/hooks, src/lib (api/constants/supabase/payments), src/services, src/types, src/__tests__.

## Database
Browser: `createClient()` from `@/lib/supabase/client`. Server/API: `await createClient()` from `@/lib/supabase/server`. Admin: `createAdminClient()` from `@/lib/supabase/admin`. Tables: snake_case; TypeScript types: camelCase.

## Zod Validation & API Patterns
```typescript
// Schema
import { z } from 'zod'
export const createListingSchema = z.object({
  title: z.string().min(1).max(200),
  price_per_unit: z.number().int().positive(),
  unit: z.enum(['kg', 'tonne', 'bag', 'crate', 'piece']),
})

// API: use response helpers from @/lib/api/responses
import { apiSuccess, apiBadRequest } from '@/lib/api/responses'
export async function POST(req: Request) {
  const result = createListingSchema.safeParse(await req.json())
  if (!result.success) return apiBadRequest(result.error.errors[0].message)
  return apiSuccess({ data: result.data })
}
```

## Database Patterns
- Use parameterized queries: `.eq()`, `.insert()`, `.update()` not raw SQL
- Financial transactions: Supabase RPC with `FOR UPDATE` row locking
- Soft deletes: use `deleted_at` column, filter with `.is('deleted_at', null)`
- Timestamps: `created_at`, `updated_at` with `default now()`
- UUIDs: use `gen_random_uuid()` for primary keys

## Testing
Mock Supabase with `vi.mock('@/lib/supabase/server')`. Use `vi.clearAllMocks()` in `beforeEach`. Test error handling paths. Mock Paystack/fetch.