feat: agent friendly code

Author: hsnice16

.claude/hooks/stop-guard.sh

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Stop-hook guard for agent-friendly-code.
+#
+# If the turn changed any watched source file AND the model has not yet
+# been redirected this cycle, block the stop and tell the model to invoke
+# `/post-change-check`. On the second Stop (`stop_hook_active: true`) the
+# guard steps aside — the documented escape hatch that prevents infinite
+# re-entry.
+
+set -eu
+
+input="$(cat)"
+
+# Anti-loop: let the turn end if we already blocked once this cycle.
+if printf '%s' "$input" | grep -qE '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then
+  exit 0
+fi
+
+paths="app components lib scripts .claude biome.json lefthook.yml package.json tsconfig.json next.config.ts"
+modified="$(git diff --name-only HEAD -- $paths 2>/dev/null || true)"
+untracked="$(git ls-files --others --exclude-standard -- $paths 2>/dev/null || true)"
+changed="$(printf '%s\n%s' "$modified" "$untracked" | sed '/^$/d')"
+
+if [ -z "$changed" ]; then
+  printf '\n✓ Turn finished. No source-file changes detected.\n'
+  exit 0
+fi
+
+file_list="$(printf '%s\n' "$changed" | sed 's/^/  • /')"
+
+# Build the reason text, then let python3 produce safely-escaped JSON.
+printf '%s\n' \
+  "Source files changed this turn:" \
+  "$file_list" \
+  "" \
+  "Invoke the /post-change-check skill NOW (docs-sync audit + /code-review + /quality-check)." \
+  "Do not close the turn until it has run. Continue and call the skill via the Skill tool." \
+  | python3 -c 'import json,sys; print(json.dumps({"decision":"block","reason":sys.stdin.read().rstrip()}))'

.claude/settings.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "printf '\\n📦 Agent Friendly Code — current release: 0.1.0\\n  • Read AGENTS.md for conventions, CONTRIBUTING.md for the PR workflow.\\n  • Roadmap: 0.2.0 (dogfood) → 0.3.0 (benchmark harness) → 0.4.0 (ecosystem integration) → 0.5.0 (alternatives) → 0.6.0 (registry overlay) → 0.7.0 (history-aware signals) → 1.0.0 (production stability) → 1.1.0 (at-scale GitHub indexing).\\n  • Changelog rule: user-facing capabilities only. Codebase hygiene (CI / linter / tests / CONTRIBUTING) does NOT go in lib/changelog.ts.\\n'"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-guard.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/code-review/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: code-review
+description: Reviews code changes for repo-specific best practices — Tailwind usage, constants/utils extraction, I/O boundary, React Server Components, and component reuse. Triggers during PR review or after non-trivial edits to app/, components/, or lib/.
+---
+
+# Code review — repo best practices
+
+Run through this checklist on any diff. Flag violations with the specific line and the suggested fix.
+
+## Tailwind
+
+- **Prefer utilities over custom classes.** If a pattern can be expressed with existing Tailwind utilities, use them. Don't add a custom class in `app/globals.css` unless the pattern repeats 3+ times with the same composition.
+- **Use the `@theme` tokens** (`bg-surface`, `text-ink`, `border-line`, etc.) — never hardcode hex in JSX.
+- **No `style={{ ... }}`** unless the value is dynamic (e.g. `width: ${pct}%`). Static styling belongs in className.
+- **No `@apply`** in `globals.css` (Tailwind 4 best practice — put the utilities on the element instead, or extract a React component).
+
+## Constants + utils
+
+- Magic numbers → `lib/constants/` (e.g. `SCORE_THRESHOLD_GOOD`, `LEADERBOARD_PAGE_SIZE`).
+- Repeated formatting → `lib/utils/format.ts` (`compactStars`, `relativeTime`, `hostLabel`).
+- Repeated scoring logic → `lib/utils/score.ts` (`scoreTier`, `TIER_TEXT_CLASS`, `TIER_BG_CLASS`).
+- A helper that's used once doesn't belong in `utils/`; inline it.
+
+## I/O boundary (architecturally important)
+
+- **`lib/scoring/` stays pure** — no DB imports, no HTTP, no side effects.
+- **All SQL in `lib/db.ts`.** Don't call `db.prepare(...)` from pages or components.
+- **Clients in `lib/clients/`** — `git.ts` for cloning, `github.ts` for host APIs.
+- Pages and scripts are thin wrappers.
+
+## React Server Components
+
+- **Default to server components.** Only add `"use client"` when you need state, effects, browser APIs, or event handlers.
+- **Fetch data in pages**, pass props down. Components don't fetch.
+- **Use `<Link>` from `next/link`** for internal navigation, not `<a href>`.
+- **Query params over client state** where possible (model filter, pagination, search).
+
+## Components
+
+- If you're writing the same markup 2–3 times, extract a component into `components/`.
+- Components are presentational — no data fetching, no side effects.
+- Props are typed explicitly; avoid `any`.
+
+## Icons
+
+Only `@phosphor-icons/react`. Block Lucide, Heroicons, React Icons, inline SVG, emoji-as-icon. Import server components from `@phosphor-icons/react/dist/ssr`; client components from the root entry.
+
+## Accessibility (quick pass — delegate deeper checks to `quality-check`)
+
+- Icon-only affordances need `aria-label`.
+- Interactive elements are keyboard-reachable.
+- No color-only signals (pair color with text or icon).
+
+## Security
+
+- Parameterised SQL only.
+- No `dangerouslySetInnerHTML`.
+- External links include `rel="noopener"`.
+- Never execute code from a cloned repo.
+
+## Response format when reviewing
+
+Group findings by severity:
+
+- **Must fix**: breaks conventions, security issues, accessibility blockers.
+- **Should fix**: best-practice violations, missing extractions.
+- **Consider**: minor polish.
+
+Each finding cites the file + line and suggests the exact fix.

.claude/skills/post-change-check/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: post-change-check
+description: Orchestrates the end-of-turn review after non-trivial edits to app/, components/, lib/, scripts/, or config files. Runs the docs-sync audit, invokes the code-review and quality-check skills on the diff, and flags anything still missing before the turn can close.
+---
+
+# Post-change check — docs sync + code review + quality sweep
+
+Run this when a turn has made code changes and you're about to report done. It's the one stop that verifies **the work is coherent** (docs and code aligned) **and correct** (conventions followed).
+
+## When to run
+
+- Auto-invoke yourself when a turn edits any of: `app/**`, `components/**`, `lib/**`, `scripts/**`, `.claude/**`, `lefthook.yml`, `biome.json`, `package.json`, `tsconfig.json`, `next.config.ts`.
+- User can also invoke manually: `/post-change-check`.
+- **Skip** for pure typo fixes, comment tweaks, or changes entirely inside `tasks/` and `data/`.
+
+## How to run
+
+Work the four phases **in order**. Don't skip ahead — the docs phase often surfaces issues code review won't.
+
+### Phase 1 — Collect the diff
+
+1. `git status --short` — see what moved.
+2. `git diff --stat HEAD` — scope.
+3. `git diff HEAD -- app/ components/ lib/ scripts/` — the actual changes.
+
+Keep a mental list of: touched files, added/removed exports, new deps, new env vars, new routes.
+
+### Phase 2 — Docs sync audit
+
+For each category below, decide **yes / no / N/A**, then act on the yeses:
+
+- **`lib/changelog.ts` under the current release bucket**
+  - Yes **only** if the change ships a user-facing capability (something a dashboard visitor, API caller, or maintainer of a listed repo can observe) **and** that capability maps to a `lib/roadmap.ts` entry or a `tasks/` file whose `Status` just flipped to `done`.
+  - No for codebase hygiene (CI, linter, pre-commit, tests), contributor docs (CONTRIBUTING, PR templates), internal refactors, dep bumps, directory moves, or UI polish without a semantic change.
+  - Action: append a one-line capability bullet (newest-first) **and** delete the matching item from `lib/roadmap.ts` — moved, not duplicated.
+- **`lib/roadmap.ts` integrity**
+  - Every item must point to a real `tasks/X.Y.Z/NN-*.md` file — no dangling `taskFile` references.
+  - Adding a roadmap entry requires adding its task file in the same PR. Don't split.
+  - Released versions don't live on the roadmap; they move to `lib/changelog.ts` with a release label.
+- **`tasks/X.Y.Z/` files**
+  - Yes if scope shifted, a task was partly/fully completed, or a new sub-task emerged.
+  - Action: update the file's `**Status**:` header (`planned` / `in_progress` / `done`) and its "What shipped" section.
+- **`AGENTS.md`**
+  - Yes if stack, directory layout, conventions, or I/O boundary changed.
+  - Specifics:
+    - Stack changes (Next.js / React / Tailwind / Bun / DB driver) → update the **Stack** bullets + cross-check with `README.md`'s Stack & rationale table.
+    - New top-level folder → update the **Layout** tree.
+    - New page in `app/` → mention in the **Layout** tree and link from the nav in `app/layout.tsx`.
+    - New signal / model / host → ensure the matching "Adding a …" section in `AGENTS.md` is still accurate.
+    - New convention or constraint → add a bullet under **Conventions**.
+- **`README.md`**
+  - Yes if a product-facing behaviour, command, or screenshot changed.
+  - Specifics: stack changes must match the `AGENTS.md` stack list; quickstart commands must actually work (`bun install`, `bun run prepare-hooks`, `bun run dev`, `bun run score <url>`); prior-art table updated if we've encountered new competitors since last sync.
+- **`CONTRIBUTING.md`**
+  - Yes if the branch/commit/PR flow or review bar changed, or if the security-contact email moved.
+- **`.env.example`**
+  - Yes if a new env var was introduced.
+  - Action: document with a one-line comment above the line.
+- **`.claude/skills/*`**
+  - Yes if a new agent workflow was added or an existing one changed.
+  - Action: update or create a skill file.
+
+Report each as `✓ updated`, `✓ N/A — reason`, or `✗ missing — file:line where it should go`.
+
+### Phase 3 — Code review
+
+Invoke the `code-review` skill on the diff. Its checklist:
+
+- Tailwind-first (utilities > custom classes, `@theme` tokens > hex, no `@apply` in `globals.css`).
+- Constants / utils extracted when the rule-of-three is hit.
+- I/O boundary held — `lib/scoring/` stays pure, all SQL in `lib/db.ts`.
+- Server components default, client only when interactivity demands it.
+- Components presentational — no data fetching, no effects.
+- Phosphor icons only.
+
+Report findings in severity order: **Must fix** / **Should fix** / **Consider**.
+
+### Phase 4 — Quality sweep
+
+Invoke the `quality-check` skill on the diff. Four dimensions:
+
+- **Accessibility**: landmarks, aria, contrast, reduced-motion, keyboard reachability.
+- **Responsiveness**: 320 → 1080+, mobile nav, table overflow, line-length caps.
+- **Performance**: RSC default, `next/script` for third-party, bundle weight, prepared statements.
+- **Security**: parameterised SQL, no `dangerouslySetInnerHTML`, `rel="noopener"` on external links, clone safety.
+
+Report Pass / Fail / Needs manual check per dimension.
+
+## Output format
+
+Print a single consolidated report:
+
+```
+Post-change check — <N> files touched
+
+Docs sync
+  ✓ lib/changelog.ts — bullet added
+  ✓ N/A — README.md (no product-facing change)
+  ✗ tasks/0.2.0/01-tests.md — status still "planned" but harness already committed; flip to in_progress
+
+Code review
+  Must fix: <none> | <file:line — why>
+  Should fix: …
+  Consider: …
+
+Quality
+  a11y:  pass
+  responsive: pass
+  performance: pass — flagged `new-dep@1.2.3` at 73 KB gz, justify or swap
+  security: pass
+
+Next steps: <bullet list or "clean, ready to commit">
+```
+
+If every phase is clean, say so plainly in one line. Don't invent findings to look thorough.
+
+## What this skill does NOT do
+
+- It does not run tests, biome, or tsc — those are the pre-commit hook's job (`lefthook.yml`).
+- It does not push, commit, or open PRs.
+- It does not modify the codebase beyond the docs updates in Phase 2 (changelog / tasks / AGENTS / README).

.claude/skills/quality-check/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: quality-check
+description: Reviews code changes against accessibility, responsiveness, performance, and security standards. Triggers on PR review or after non-trivial changes to app/, components/, or lib/.
+---
+
+# Quality check — a11y, responsive, performant, secure
+
+Run the four checks below on any diff affecting UI or I/O. Report findings grouped by dimension.
+
+## Accessibility
+
+- **Landmarks**: one `<main>`, one `<h1>` per page, `<nav aria-label>` on every nav.
+- **Semantic HTML**: `<button>` for buttons, `<a>` for links, `<form>` for forms. No `<div onClick>`.
+- **aria-label** on every icon-only interactive element (hamburger button, external-link icon, medal chips, score bars).
+- **Keyboard reachability**: every interactive element is focusable and visibly shows focus. The global `*:focus-visible` ring covers most cases; verify for custom controls.
+- **Color contrast AA**: `text-muted` on `bg-surface` and `bg-surface-2` must hit 4.5:1 for body text (3:1 for large). Run the numbers if you change color tokens.
+- **Reduced motion**: transitions/animations respect `@media (prefers-reduced-motion: reduce)`.
+- **Form labels**: every input has an associated `<label>` (visible or `sr-only`).
+
+## Responsive
+
+- Viewport sizes to verify: **320 px**, **640 px** (sm), **768 px** (md), **1080 px+** (container max).
+- **Nav**: collapses to `<MobileNav>` hamburger below md.
+- **Tables**: wrapped in `overflow-x-auto` — never force horizontal page scroll.
+- **Hero / headings**: scale with `sm:` or `md:` prefix.
+- **Grids**: fall back to `grid-cols-1` on narrow.
+- **Flex rows** that hold long content: `flex-col sm:flex-row` to stack on mobile.
+- **Hero paragraph and body text**: max ~70ch to keep line length readable.
+
+## Performance
+
+- **Server components by default.** Client components only when necessary.
+- **Third-party scripts** loaded via `next/script` with `strategy="afterInteractive"` — see `GoogleAnalytics.tsx`.
+- **No client-side data fetching** for rendering — use the DB in a Server Component or API route.
+- **Image optimisation** via `<Image>` when we add images; no `<img>` unless the src is dynamic and unknown at build.
+- **Bundle weight**: flag any new dep > 50 KB gzipped. Justify or use a smaller alternative.
+- **Database queries** are `prepare`d once and reused where hot.
+
+## Security
+
+- **SQL parameterisation**: every query uses `?` placeholders. No string concatenation.
+- **No `dangerouslySetInnerHTML`.**
+- **External URLs** in `<a target="_blank">` always include `rel="noopener"`.
+- **User input at every boundary** is validated: `parseRepoUrl` for repo URLs, `Number.isFinite` for numeric params, length caps on search strings.
+- **Clone safety**: `git clone --depth 1 --single-branch`; never execute code from a clone (no `bun install`, no `npm install`, no post-clone scripts).
+- **Secrets never in code**. `.env.example` documents required vars; `.env.local` is gitignored.
+- **Operational concerns** (flag for ops review, not code):
+  - Disk cap on `tmp-clones/`.
+  - Rate limit on the public API before launch.
+  - Sandbox the cloner in a container for production.
+
+## Response format
+
+For each dimension, list:
+
+- **Pass** items (short, one line each).
+- **Fail** items with file:line + the fix.
+- **Needs manual check** items (e.g. "contrast pass requires a visual check at these two color pairings").
+
+If everything passes, say so plainly. Don't invent issues to look thorough.

.env.example

@@ -0,0 +1,15 @@
+PORT=3000
+NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
+NEXT_PUBLIC_APP_URL=https://agent-friendly-code.vercel.app
+
+# ---------- Host API tokens ----------
+# Raise rate limits when fetching repo metadata (stars, default branch) during
+# `bun run score` / `bun run seed`. Scoring works without these, just slower
+# against the unauthenticated ceiling.
+
+# Classic or fine-grained PAT with public_repo read access is enough.
+GITHUB_TOKEN=
+
+# GitLab personal access token with read_api scope.
+GITLAB_TOKEN=
+

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @hsnice16

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: hsnice16

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Lint · Format · Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.2.16
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      - name: Biome check (lint + format)
+        run: bun x @biomejs/biome ci .
+
+      - name: Typecheck
+        run: bun x tsc --noEmit

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.next/
+data/*.db
+data/*.db-journal
+tmp-clones/
+.env
+.env.local
+.DS_Store
+next-env.d.ts