Starter Kits: Make Any Repo Agent-Ready

# AGENTS.md
 
> Operating instructions for coding agents working in this repo. Plain Markdown, no schema.
> The closest AGENTS.md to the file being edited wins; an explicit chat instruction wins over all.
 
## Project overview
- Next.js 14 App Router + TypeScript, static export.
- Entry points: `app/` (routes), `lib/` (shared logic), `components/` (UI).
 
## Setup
- Install: `pnpm install`  (this repo uses pnpm — do not use npm or yarn)
- Integration tests need a local Postgres: `docker compose up -d db` first.
 
## Build, test, lint
- Build: `pnpm build`
- Test (all): `pnpm test`   ·   single file: `pnpm test <path>`
- Lint (must be zero warnings): `pnpm lint`
- Typecheck: `pnpm typecheck`
 
## Code style
- TypeScript strict; no `any` that breaks the build.
- 2-space indent; named exports; colocate tests as `*.test.ts`.
 
## Conventions & constraints
- Never edit `legacy/` or generated output in `dist/`.
- Keep the public API in `lib/api/` backward compatible.
- Use the `@/*` path alias (maps to repo root); never deep relative imports across packages.
 
## Definition of done
Before claiming a task is finished: `pnpm lint` clean, `pnpm test` green, `pnpm typecheck`
passes, no new TODOs left in changed files.
 
## PR / commit
- Conventional Commits (`feat:`, `fix:`, `chore:`). One logical change per PR.
- Do not commit unless explicitly asked.
 
## Review guidelines
- Don't log PII. Verify auth middleware wraps every route.
- Flag typos/grammar in user-facing strings as P0.

@AGENTS.md
 
# CLAUDE.md
 
<!-- The shared briefing above is imported from AGENTS.md so Claude Code and every
     AGENTS.md-native tool read one source of truth. Add ONLY Claude-specific lines below. -->
 
## Claude Code specifics
- Use plan mode before multi-file changes under `lib/api/`.
- Run a single test with `pnpm test <path>`, not the whole suite, while iterating.
- Money-handling rules live in `lib/payments/CLAUDE.md` and load on demand when you work there.

@./AGENTS.md
 
# GEMINI.md
 
<!-- Imports the shared AGENTS.md briefing. Gemini-only notes go below. -->
 
## Gemini CLI specifics
- Prefer `gemini -m gemini-2.5-flash` for quick edits; reserve the pro model for design work.

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

---
description: TypeScript/React component conventions for this repo
globs: src/components/**/*.tsx
alwaysApply: false
---
 
# Component conventions
 
- Function components only; no class components.
- Props typed with an exported `interface`, never inline object types.
- Co-locate a `*.test.tsx` beside every component.
- Use the design tokens in `styles/tokens.css`; never hardcode hex colors.
- Reference `@/lib/api` for data fetching — do not call `fetch` directly in components.

# Copilot instructions
 
The canonical project briefing lives in `AGENTS.md` at the repo root and Copilot reads it
automatically; this file adds Copilot-specific guidance only.
 
- This repo uses **pnpm**. Never suggest `npm install` or `yarn`.
- Prefer small, reviewable diffs; explain non-obvious changes in the PR body.
- TypeScript strict mode is on — never introduce `any`.
- For test files, follow the existing `*.test.ts` patterns in the same directory.

{
  "permissions": {
    "allow": [
      "Bash(pnpm test *)",
      "Bash(pnpm lint *)",
      "Bash(pnpm build *)",
      "Bash(pnpm typecheck *)",
      "Bash(git status *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rm -rf *)",
      "Bash(curl *)"
    ]
  },
  "defaultMode": "default",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --write"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# Stop-hook gate: block the turn from ending until the test suite passes.
set -euo pipefail
 
input="$(cat)"   # Claude Code feeds hook JSON on stdin
 
# Don't re-fire on a turn we already blocked (prevents the 8-block override loop).
if [ "$(printf '%s' "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi
 
if pnpm test >/tmp/test-gate.log 2>&1; then
  exit 0   # tests green: allow the stop
else
  echo "Tests are failing — keep working until they pass:" >&2
  tail -n 20 /tmp/test-gate.log >&2
  exit 2   # block the stop; stderr is fed back to Claude
fi

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/test-gate.sh"
          }
        ]
      }
    ]
  }
}

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks
  what changed, wants a commit message, or asks to review their diff.
allowed-tools: Bash(git diff *) Bash(git status *)
---
 
## Current changes
 
!`git diff HEAD`
 
## Instructions
 
Summarize the changes above in two or three bullet points, then list any risks you notice —
missing error handling, hardcoded values, or tests that need updating. If the diff is empty,
say there are no uncommitted changes.