Agent Instructions

Package Manager

Use pnpm: pnpm install, pnpm dev, pnpm cli <cmd>

Commit Attribution

AI commits MUST include:

Co-Authored-By: <model-name> <noreply@anthropic.com>

Use your actual model name (e.g., Claude Sonnet 4, Claude Opus 4.5).

API Routes

Routes require session validation except /sign-in, /api/auth/*, /api/cron/*, /api/webhooks/*.

import { NextResponse } from 'next/server';
import { wrapRouteHandlerWithSentry } from '@sentry/nextjs';
import { getSession } from '@/lib/auth';

async function handler(request: Request) {
  const session = await getSession();
  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  // handler logic
}

export const GET = wrapRouteHandlerWithSentry(handler, {
  method: 'GET',
  parameterizedRoute: '/api/your-route',
});

Navigation

• Use <AppLink> for internal links (preserves ?days=N)
• Use useTimeRange() hook to access/update time range

Database

Use db-migrate skill for schema changes. See .claude/skills/db-migrate/SKILL.md

CLI

Model Names

Normalize at write-time via normalizeModelName(): sonnet-4, opus-4.5 (T), haiku-3.5 (HT)

Adoption Stages

• Positive framing only (no "Struggling"/"At Risk")
• No gamification (no progress bars, XP, "level up")
• Stages: Exploring → Building Momentum → In the Flow → Power User
• Based on intensity (avg tokens/day), not frequency
• Inactive = 30+ days (hide by default)
• Thresholds: Power User 3M+, In Flow 1M+, Building Momentum 250K+
• See src/lib/adoption.ts

Testing

Use write-tests skill. See .claude/skills/write-tests/SKILL.md

pnpm test              # Run all tests
pnpm test:watch        # Watch mode

Frontend & UI

Use ui-design skill. See .claude/skills/ui-design/SKILL.md

Tips & Guides

Use write-tip skill. See .claude/skills/write-tip/SKILL.md

Documentation

Use write-docs skill. See .claude/skills/write-docs/SKILL.md