New Feature

Phase 2: Implement

Once the plan is approved:

1. If database changes are needed:

   • Update prisma/schema.prisma
   • Run npx prisma migrate dev --name <descriptive-name>
   • Run npx prisma generate

2. If the feature involves ARCA/SiRADIG automation (src/lib/automation/), use /implement-loop to iterate: test against live SiRADIG, observe failures with agent-browser, fix, and re-test until the automation succeeds. Then continue to Phase 3.

3. Implement the feature following these conventions:

   • Business logic in src/lib/ (organized by domain)
   • API routes in src/app/api/ (mirror domain structure, validate session?.user?.id)
   • UI components in src/components/ (split by feature domain)
   • Use Decimal.js for all monetary calculations
   • Use Zod for all input validation
   • Spanish names only in ARCA/SiRADIG automation code, English everywhere else
   • Follow the Jony Ive design system: clean whites, border-gray-200, bg-gray-50, generous whitespace
   • All UI must be mobile-friendly (mobile-first). Rules:
     • Design for 320px minimum width first, then enhance for larger screens with sm:, md:, lg: breakpoints.
     • Never use fixed widths without responsive alternatives (e.g., w-full sm:w-[280px], not w-[280px]).
     • Menus, modals, and sheets must be full-width on mobile (w-full sm:max-w-md).
     • Data tables must use card layouts or horizontal scroll (overflow-x-auto) on mobile.
     • Touch targets must be at least 44px (use min-h-[44px] min-w-[44px] on interactive elements).
     • Use flex-col sm:flex-row for layouts that stack vertically on mobile.
     • Add overflow-x-hidden to page containers to prevent horizontal scroll bleed.
     • Test that text doesn't overflow or get clipped on narrow screens.
   • All UI must support dark mode. The project uses next-themes with Tailwind's dark: variant (@custom-variant dark (&:is(.dark *))). Rules:
     • Never use raw color classes like bg-gray-50, , without a counterpart. Prefer semantic tokens (, , , ) which auto-adapt.

Phase 3: Test

1. Write unit tests for all new business logic in src/lib/:

   • Create __tests__/ directory alongside the module
   • Use Vitest with describe/it blocks
   • Test happy paths, edge cases, and error conditions
   • Use @/ path aliases for imports

2. Write tests for new validators (Zod schemas).

3. If the feature includes new API routes, consider integration test patterns.

4. Run the full test suite: npm run test

   • ALL tests must pass (existing + new)
   • If a test fails, fix the issue and re-run

Phase 4: Validate

Run the full CI check locally:

npm run lint && npm run format:check && npm run build && npm run test

All four commands must pass. If any fail, fix and re-run.

Phase 5: Document & Codify

1. Update CLAUDE.md if the feature introduces:

   • New route groups or API routes
   • New domain directories in src/lib/ or src/components/
   • New patterns or conventions
   • New environment variables
   • New database models

2. Create or update a spec in specs/ if acceptance criteria were defined.

3. Mark the spec as implemented with a status: implemented field.

Phase 6: Summary

Present a summary:

• What was implemented (files created/modified)
• Test coverage added
• Any decisions made and why
• Suggestions for follow-up work