Skip to content

agents.md

Latest commit

 

History

History
100 lines (72 loc) · 2.7 KB

agents.md

File metadata and controls

100 lines (72 loc) · 2.7 KB
Raw

GitReverse Agent Instructions

This is a Next.js 16, React 19, TypeScript, Tailwind CSS 4 project.

Critical Next.js rule

This is not older Next.js. Before changing App Router, route handlers, caching, server/client boundaries, or font behavior, check the local Next.js docs in node_modules/next/dist/docs/. Do not rely only on training-memory assumptions.

Product

GitReverse is a developer utility that converts a public GitHub repository into a concise natural-language prompt that can be pasted into Codex, Cursor, Claude Code, ChatGPT code mode, or another AI coding assistant.

The app must feel fast, simple, and repeatable. Think "toothbrush for developers."

Core flow

User enters:

  • https://github.com/owner/repo
  • github.com/owner/repo
  • owner/repo

The app fetches:

  • metadata
  • stars
  • primary language
  • description
  • topics
  • README, max 8000 chars
  • depth-1 file tree

Then it sends the context to an LLM and returns one 120-200 word natural-language prompt focused on product intent, not implementation details.

LLM providers

Support only:

  • OpenRouter
  • Google AI Studio

Default model:

  • OpenRouter: google/gemini-2.5-pro
  • Google AI Studio: gemini-2.5-pro

Keep API keys server-side only.

Optional services

Supabase is optional. If Supabase env vars are missing:

  • quick reverse still works
  • custom reverse still works
  • library returns an empty state
  • view tracking silently skips
  • the app must not crash

Custom reverse service is optional. If unavailable, return a clean 503 with a helpful message.

UI contract

Do not casually change brand tokens.

Required style:

  • background #FFFDF8
  • primary accent #d31611
  • input background #fff4da
  • hover yellow #ffc480
  • borders zinc-900, 3px solid
  • offset shadow cards using absolute inset shadow layer with translate-x-2 translate-y-2
  • Geist Sans and Geist Mono via next/font
  • sticky navbar
  • logo: Git + red Reverse

Code quality rules

Prefer small focused modules.

Avoid huge files. Split:

  • LLM provider logic into lib/llm
  • GitHub fetching/context into lib/github
  • Supabase/no-op cache into lib/cache
  • custom reverse/SSE proxy into lib/custom
  • reusable UI into focused components

Use stable typed error codes for API responses.

Never expose server env vars to client components.

Do not introduce authentication, payment, or Stripe logic into the core flow unless specifically requested.

Testing checklist

Before finishing:

  • pnpm lint
  • pnpm build
  • Test with OpenRouter only
  • Test with Google AI Studio only
  • Test with no Supabase env vars
  • Test invalid repo input
  • Test missing README
  • Test GitHub main/master fallback
  • Test manual service unavailable
  • Test /owner/repo/tree/... redirect