@googlarz/agents-sync 1.4.0

package/docs/agents-md-spec.md

@@ -0,0 +1,233 @@
+# AGENTS.md Specification
+
+> Version 1.0  ·  Published by [agents-sync](https://github.com/googlarz/agents-sync)
+
+AGENTS.md is a plain-text file at the root of a software project that describes the project's conventions, boundaries, and context for AI coding assistants. This document is the canonical format specification.
+
+---
+
+## Overview
+
+AGENTS.md serves as the **single source of truth** for AI context in a project. Tool-specific files (CLAUDE.md, .cursorrules, copilot-instructions.md, GEMINI.md, .windsurfrules, .clinerules) are derived from it by agents-sync. Authors edit AGENTS.md; agents-sync keeps the derived files in sync.
+
+```
+AGENTS.md  ──►  CLAUDE.md           (Claude Code)
+           ──►  .cursorrules         (Cursor)
+           ──►  copilot-instructions.md  (GitHub Copilot)
+           ──►  GEMINI.md            (Gemini CLI)
+           ──►  .windsurfrules       (Windsurf)
+           ──►  .clinerules          (Cline)
+```
+
+---
+
+## File Location
+
+Always at the **project root**: `<project-root>/AGENTS.md`
+
+---
+
+## Canonical Structure
+
+```markdown
+# AGENTS.md
+
+## Project
+<!-- Brief project description. One paragraph. -->
+
+## Stack
+<!-- Technology choices: language, framework, database, test runner, deploy target. -->
+
+## Architecture
+<!-- Key directories and what lives in them. Entry points. -->
+
+## Conventions
+<!-- Specific rules the AI must follow when writing code. -->
+
+## Boundaries
+### Always
+<!-- Things the AI should always do. -->
+### Ask first
+<!-- Things the AI should confirm before doing. -->
+### Never
+<!-- Hard prohibitions. These are machine-checkable by agents-sync lint. -->
+
+## Testing
+<!-- How to run tests. Where tests live. Coverage expectations. -->
+
+## Deployment
+<!-- How to deploy. Environment variables. CI/CD details. -->
+
+## Gotchas
+<!-- Known pitfalls, surprising behavior, non-obvious constraints. -->
+```
+
+---
+
+## Section Reference
+
+### `## Project`
+
+A short description of what the project does and who it's for. Include the project name.
+
+```markdown
+## Project
+Acme Billing — a SaaS invoice management platform built for small businesses.
+Backend: Node.js / Express. Frontend: React + TypeScript.
+```
+
+### `## Stack`
+
+List the concrete technology choices. Be specific — include package names and versions where relevant.
+
+```markdown
+## Stack
+- **Language**: TypeScript 5.4
+- **Framework**: Next.js 14 (App Router)
+- **Database**: PostgreSQL 16 via Prisma ORM
+- **Auth**: NextAuth.js v5
+- **Testing**: Vitest + React Testing Library
+- **Deploy**: Vercel (preview + production)
+```
+
+### `## Architecture`
+
+Describe how the codebase is organized. Focus on what the AI needs to know to place files correctly.
+
+```markdown
+## Architecture
+- `app/` — Next.js App Router pages and layouts
+- `app/api/` — API route handlers
+- `src/lib/` — shared utilities (no framework dependencies)
+- `src/components/` — reusable React components
+- `src/db/` — Prisma client and query helpers
+- `tests/` — unit and integration tests mirroring `src/`
+```
+
+### `## Conventions`
+
+Specific, observable rules for the AI to follow. Every convention must be **falsifiable** — it should be possible to look at a piece of code and determine whether the convention is followed.
+
+**Good conventions:**
+```markdown
+- Use named exports only; no default exports except in `app/` pages
+- File names: kebab-case (e.g., `user-profile.ts`, not `UserProfile.ts`)
+- API routes return `{ data, error }` envelopes — never naked objects
+- All DB queries go through `src/db/` helpers, never direct Prisma client calls
+```
+
+**Bad conventions (too vague):**
+```markdown
+- Follow best practices
+- Write clean code
+- Keep things simple
+```
+
+### `## Boundaries`
+
+Three tiers of constraint:
+
+| Tier | Meaning | AI behavior |
+|------|---------|-------------|
+| **Always** | Must do by default | Do this in every relevant context |
+| **Ask first** | Requires human approval | Propose and wait for a ✓ before acting |
+| **Never** | Hard prohibitions | Refuse; explain the rule if asked |
+
+```markdown
+### Always
+- Run `npm test` before considering a task complete
+- Add a test for every new function in `src/lib/`
+- Import from `@/lib/db` — never use PrismaClient directly
+
+### Ask first
+- Adding or removing npm dependencies
+- Changing the database schema
+- Modifying CI/CD pipeline files
+
+### Never
+- Commit `.env` files or any file containing secrets
+- Use `console.log` in production code (use the `logger` utility instead)
+- Use TypeScript `any` type (use `unknown` or proper types)
+- Call `process.env` directly (use `src/lib/config.ts` instead)
+```
+
+> **Note:** Rules in `### Never` are checked by `agents-sync lint`. Write them as specific, machine-checkable statements.
+
+### `## Testing`
+
+```markdown
+## Testing
+- **Framework**: Vitest
+- **Run all**: `npm test`
+- **Run unit**: `npm run test:unit`
+- **Coverage**: `npm run test:coverage` (target: 80%)
+- **Location**: `tests/` mirrors `src/` structure; test files named `*.test.ts`
+- **Policy**: every new public function must have at least one test
+```
+
+### `## Deployment`
+
+```markdown
+## Deployment
+- **Target**: Vercel (auto-deploy from `main`)
+- **Preview**: every PR gets a preview URL
+- **Env vars**: see `.env.example` — required: `DATABASE_URL`, `NEXTAUTH_SECRET`
+- **Migrations**: `npx prisma migrate deploy` (runs automatically in CI)
+```
+
+### `## Gotchas`
+
+Surprising behavior, footguns, or non-obvious constraints that would catch a new contributor (or AI) off guard.
+
+```markdown
+## Gotchas
+- `lib/auth.ts` wraps NextAuth — do not import `next-auth` directly elsewhere
+- Prisma queries in API routes must be wrapped in try/catch; errors are not automatically forwarded
+- `app/` directory uses React Server Components by default — add `"use client"` explicitly for interactive components
+- The `tests/` directory uses a separate `tsconfig.test.json` — do not add test utilities to the main `tsconfig.json`
+```
+
+---
+
+## Custom Sections
+
+agents-sync preserves any content inside these markers across re-syncs:
+
+```markdown
+<!-- AGENTS-SYNC:CUSTOM:START -->
+...your hand-written content here...
+<!-- AGENTS-SYNC:CUSTOM:END -->
+```
+
+Use custom sections for project-specific context that agents-sync cannot detect automatically (e.g., business logic rules, team preferences, domain-specific terminology).
+
+---
+
+## Machine-Checkable Rules
+
+`agents-sync lint` parses the `### Never` section and checks for violations using pattern matching. To maximize automated coverage, write Never rules in one of these forms:
+
+| Pattern | Example |
+|---------|---------|
+| `console.log` | "Never use `console.log`" |
+| TypeScript `any` | "Never use TypeScript `any` type" |
+| Default exports | "Never use default exports" |
+| Direct import | "Never import `PrismaClient` directly" |
+| `.env` in git | "Never commit `.env` files" |
+| `process.env` access | "Never access `process.env` directly" |
+
+Rules that don't match a known pattern are marked `skipped: No automated check available` in the lint report — they are still enforced by convention but not automatically verified.
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | 2026-05-20 | Initial specification |
+
+---
+
+## Contributing
+
+To propose changes to this specification, open an issue at [googlarz/agents-sync](https://github.com/googlarz/agents-sync/issues) with the label `spec`.

package/docs/examples/.clinerules

@@ -0,0 +1,29 @@
+# .clinerules — managed by agents-sync v1.0.0
+# Language: TypeScript / Next.js 14
+
+## Conventions
+
+- kebab-case filenames throughout
+- Named exports only (default exports for Next.js pages/layouts only)
+- Zod for all external input validation
+- Co-locate tests (Button.test.tsx next to Button.tsx)
+- Server components by default; 'use client' only when needed
+
+## Always
+
+- Run npm test before committing
+- Validate external API responses with Zod
+- Check middleware.ts before adding /api/ routes
+- Use src/lib/db.ts for all Prisma queries
+
+## Never
+
+- Commit .env or .env.local
+- Import PrismaClient directly (use src/lib/db.ts — pool exhaustion risk)
+- Use TypeScript any (use unknown and narrow)
+- Push directly to main
+- Use console.log in production
+
+## Tests
+
+`npm test`

package/docs/examples/.cursorrules

@@ -0,0 +1,19 @@
+# .cursorrules — managed by agents-sync v1.0.0
+# Language: TypeScript / Next.js 14
+# Run tests: npm test
+
+- Always: use kebab-case filenames (user-profile.tsx not UserProfile.tsx)
+- Always: named exports only (no default exports except Next.js page/layout components)
+- Always: validate external API responses with Zod
+- Always: co-locate tests (Button.test.tsx next to Button.tsx)
+- Always: server components by default — add 'use client' only when needed
+- Always: use cn() from lib/utils.ts for conditional classNames
+- Never: import PrismaClient directly (use src/lib/db.ts — connection pool exhaustion)
+- Never: add /api/ routes without checking middleware.ts auth coverage
+- Never: use date-fns without /utc variants (multi-timezone dashboard)
+- Never: commit .env or .env.local
+- Never: use TypeScript any — use unknown and narrow
+- Never: push directly to main
+- Never: use console.log in production (use logger utility)
+- Tests: npm test
+- Build: npm run build

package/docs/examples/.windsurfrules

@@ -0,0 +1,14 @@
+# .windsurfrules — managed by agents-sync v1.0.0
+# Language: TypeScript / Next.js 14
+
+- Always: use kebab-case filenames
+- Always: named exports only (default exports for Next.js pages/layouts only)
+- Always: validate external input with Zod
+- Always: co-locate tests (*.test.ts next to source)
+- Always: server components by default; 'use client' only when required
+- Never: DB connection is singleton — use src/lib/db.ts, not new PrismaClient()
+- Never: add API routes without checking middleware.ts auth coverage
+- Never: date comparisons without UTC — use date-fns/utc variants
+- Never: commit .env or .env.local
+- Never: TypeScript any
+- Tests: npm test

package/docs/examples/AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md
+
+<!-- Generated by agents-sync v1.0.0 on 2026-05-20 -->
+
+## Project Overview
+
+Acme Dashboard is an internal analytics and reporting platform for the sales team. Built with
+Next.js 14 App Router, PostgreSQL via Prisma ORM, and NextAuth v4 for authentication. Deployed
+on Vercel with a Neon managed Postgres instance.
+
+## Tech Stack
+
+- **Language:** TypeScript
+- **Framework:** Next.js 14 (App Router)
+- **Database:** PostgreSQL via Prisma ORM
+- **Auth:** NextAuth v4
+- **UI:** shadcn/ui + Tailwind CSS
+- **Testing:** Vitest (co-located)
+- **Deployment:** Vercel + Neon
+
+## Architecture
+
+```
+src/
+  app/           Next.js App Router pages and layouts
+  features/      Domain modules: dashboard, reports, users, billing
+  lib/           Shared utilities: db singleton, auth config, api client
+  components/    Shared UI (shadcn/ui based)
+  hooks/         Client-side React hooks
+```
+
+### Key directories
+
+- `src/app/` — Next.js App Router pages and layouts (server components by default)
+- `src/features/` — Feature modules, one directory per domain
+- `src/lib/db.ts` — Prisma client singleton (do not instantiate PrismaClient elsewhere)
+- `src/lib/auth.ts` — NextAuth configuration
+- `src/components/` — Shared, reusable UI components
+
+## Conventions
+
+1. kebab-case filenames throughout (`user-profile.tsx`, not `UserProfile.tsx`)
+2. Named exports only — no default exports except Next.js page/layout components
+3. All external API responses validated with Zod before use
+4. Co-locate tests: `Button.test.tsx` lives next to `Button.tsx`
+5. Use `cn()` from `lib/utils.ts` for conditional className strings
+6. Server components by default; add `'use client'` only when hooks or browser APIs are required
+7. All database queries go through `src/lib/db.ts` — never instantiate PrismaClient directly
+
+## Gotchas
+
+1. **Never import `PrismaClient` directly** — Vercel's serverless runtime creates a new instance
+   per invocation, exhausting the Neon connection pool. Use `src/lib/db.ts` singleton only.
+2. **All API routes require auth middleware** — the `middleware.ts` matcher protects `/api/**`.
+   Any new route outside that pattern must explicitly add auth checks.
+3. **Date comparisons must use UTC** — the dashboard serves users across timezones. Use
+   `date-fns/utc` variants (`formatUTC`, `parseISO`, etc.) not the plain `date-fns` equivalents.
+4. **`src/app/` is server-first** — avoid `useState`/`useEffect` in files under `src/app/`
+   unless they are explicitly `'use client'`. Data fetching belongs in server components.
+
+## Boundaries
+
+### Always do
+
+- Run `npm test` before committing
+- Validate external API responses with Zod
+- Check `middleware.ts` before adding new `/api/` routes
+- Use `src/lib/db.ts` for all Prisma queries
+
+### Ask first
+
+- Database schema changes (Prisma migrations affect production data)
+- Adding new npm dependencies (bundle size matters)
+- Changes to the authentication flow or session handling
+- Modifying `middleware.ts`
+
+### Never
+
+- Commit `.env` or `.env.local`
+- Instantiate `PrismaClient` outside of `src/lib/db.ts`
+- Use TypeScript `any` — use `unknown` and narrow instead
+- Push directly to `main` branch
+- Use `console.log` in production code (use the `logger` utility instead)
+
+## Testing
+
+- **Framework:** Vitest
+- **Run:** `npm test`
+- **Coverage:** `npm run test:coverage`
+- **Location:** Co-located with source (`*.test.ts` / `*.test.tsx`)
+
+## Deployment
+
+- **Target:** Vercel (automatic on push to `main`)
+- **Database:** Neon PostgreSQL (`DATABASE_URL` in environment)
+- **Migrations:** Run `npx prisma migrate deploy` after schema changes
+- **Env:** `.env.local` for local dev; Vercel dashboard for production secrets

package/docs/examples/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+<!-- Derived from AGENTS.md by agents-sync v1.0.0 on 2026-05-20 -->
+<!-- Source: AGENTS.md — edit that file, then run /agents-sync sync -->
+
+## Project Overview
+
+Acme Dashboard is an internal analytics and reporting platform for the sales team. Built with
+Next.js 14 App Router, PostgreSQL via Prisma ORM, and NextAuth v4 for authentication. Deployed
+on Vercel with a Neon managed Postgres instance.
+
+## Tech Stack
+
+- **Language:** TypeScript
+- **Framework:** Next.js 14 (App Router)
+- **Database:** PostgreSQL via Prisma ORM
+- **Auth:** NextAuth v4
+- **UI:** shadcn/ui + Tailwind CSS
+- **Testing:** Vitest (co-located)
+- **Deployment:** Vercel + Neon
+
+## Architecture
+
+- `src/app/` — Next.js App Router pages and layouts (server components by default)
+- `src/features/` — Feature modules, one directory per domain
+- `src/lib/db.ts` — Prisma client singleton (do not instantiate PrismaClient elsewhere)
+- `src/lib/auth.ts` — NextAuth configuration
+- `src/components/` — Shared, reusable UI components
+
+## Conventions
+
+1. kebab-case filenames throughout (`user-profile.tsx`, not `UserProfile.tsx`)
+2. Named exports only — no default exports except Next.js page/layout components
+3. All external API responses validated with Zod before use
+4. Co-locate tests: `Button.test.tsx` lives next to `Button.tsx`
+5. Use `cn()` from `lib/utils.ts` for conditional className strings
+6. Server components by default; add `'use client'` only when hooks or browser APIs are required
+7. All database queries go through `src/lib/db.ts`
+
+## Gotchas
+
+1. **Never import `PrismaClient` directly** — connection pool exhaustion. Use `src/lib/db.ts`.
+2. **All API routes require auth middleware** — `middleware.ts` matcher covers `/api/**`.
+3. **Date comparisons must use UTC** — use `date-fns/utc` variants throughout.
+4. **`src/app/` is server-first** — no hooks/browser APIs unless `'use client'` is declared.
+
+## Boundaries
+
+### Always do
+
+- Run `npm test` before committing
+- Validate external API responses with Zod
+- Check `middleware.ts` before adding new `/api/` routes
+- Use `src/lib/db.ts` for all Prisma queries
+
+### Ask first
+
+- Database schema changes
+- Adding new npm dependencies
+- Changes to authentication flow
+- Modifying `middleware.ts`
+
+### Never
+
+- Commit `.env` or `.env.local`
+- Instantiate `PrismaClient` outside of `src/lib/db.ts`
+- Use TypeScript `any`
+- Push directly to `main`
+- Use `console.log` in production
+
+## Commands
+
+```bash
+npm run dev          # local dev server
+npm test             # run tests
+npm run test:watch   # watch mode
+npm run build        # production build
+npm run lint         # lint
+npx prisma studio    # database GUI
+npx prisma migrate dev  # run migrations locally
+```
+
+## Claude Code notes
+
+- When adding API routes, check `middleware.ts` first to understand auth coverage
+- For UI work, use existing shadcn/ui components from `src/components/ui/`
+- Feature work lives in `src/features/<name>/` — match the existing module structure
+- The Prisma schema is in `prisma/schema.prisma`

package/docs/examples/GEMINI.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+<!-- Derived for Gemini CLI by agents-sync v1.0.0 on 2026-05-20 -->
+
+## Project Overview
+
+Acme Dashboard is an internal analytics and reporting platform for the sales team. Built with
+Next.js 14 App Router, PostgreSQL via Prisma ORM, and NextAuth v4 for authentication.
+
+## Tech Stack
+
+- TypeScript / Next.js 14 (App Router)
+- PostgreSQL via Prisma ORM
+- Auth: NextAuth v4
+- UI: shadcn/ui + Tailwind CSS
+- Testing: Vitest (co-located)
+- Deployment: Vercel + Neon
+
+## Architecture
+
+- `src/app/` — App Router pages and layouts
+- `src/features/` — Domain modules
+- `src/lib/db.ts` — Prisma client singleton
+- `src/components/` — Shared UI
+
+## Conventions
+
+1. kebab-case filenames throughout
+2. Named exports only
+3. Zod for all external input validation
+4. Co-locate tests
+5. Server components by default
+
+## Gotchas
+
+1. Never import PrismaClient directly — use src/lib/db.ts
+2. All API routes protected by middleware.ts
+3. Date comparisons must use UTC (date-fns/utc)
+
+## Boundaries
+
+### Never
+- Commit .env or .env.local
+- Instantiate PrismaClient outside src/lib/db.ts
+- Use TypeScript any
+- Push directly to main
+
+### Always do
+- Run npm test before committing
+- Validate external responses with Zod
+
+## Testing
+
+`npm test`
+
+---
+
+## Gemini CLI Notes
+
+This file is managed by [agents-sync](https://github.com/googlarz/agents-sync). Edit `AGENTS.md`
+then run `agents-sync sync` to regenerate all tool context files.

package/docs/examples/copilot-instructions.md

@@ -0,0 +1,24 @@
+<!-- Managed by agents-sync v1.0.0. Source: AGENTS.md -->
+# GitHub Copilot Instructions — Acme Dashboard
+
+**Stack:** TypeScript · Next.js 14 App Router · Prisma + Neon PostgreSQL · NextAuth v4 · shadcn/ui
+
+## Code rules
+
+- kebab-case filenames; named exports only (default exports for Next.js pages/layouts only)
+- Validate external data with Zod before use
+- Tests co-located: `Foo.test.tsx` next to `Foo.tsx`
+- Server components by default; `'use client'` only for hooks/browser APIs
+
+## Critical constraints
+
+- Database: always use `src/lib/db.ts` singleton — never `new PrismaClient()`
+- Auth: all `/api/` routes are protected by `middleware.ts`; check before adding routes
+- Dates: use `date-fns/utc` variants — dashboard is multi-timezone
+- No `console.log` in production; no TypeScript `any`; no `.env` commits
+
+## Tests
+
+```
+npm test
+```

package/docs/github-action.yml

@@ -0,0 +1,89 @@
+# agents-sync GitHub Action
+#
+# Checks for codebase drift weekly and when package.json/manifest changes.
+# Opens a PR when drift is detected so the team can review and re-sync.
+#
+# Setup:
+#   1. Copy this file to .github/workflows/agents-sync.yml in your repo
+#   2. Add ANTHROPIC_API_KEY to your repository secrets
+#      (Settings → Secrets and variables → Actions → New repository secret)
+#   3. Commit and push
+
+name: agents-sync drift check
+
+on:
+  schedule:
+    # Run every Monday at 9am UTC
+    - cron: "0 9 * * 1"
+  push:
+    paths:
+      # Re-check whenever a manifest or major structure file changes
+      - "package.json"
+      - "pyproject.toml"
+      - "Cargo.toml"
+      - "go.mod"
+      - "composer.json"
+  workflow_dispatch:
+    inputs:
+      force_sync:
+        description: "Force a full re-sync even if drift is low"
+        type: boolean
+        default: false
+
+jobs:
+  drift-check:
+    name: Check AI context drift
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Check drift
+        id: drift
+        run: npx @googlarz/agents-sync drift . --ci
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          NO_COLOR: "1"
+        # --ci exits with code 1 when drift is HIGH; the step fails,
+        # which triggers the sync step below.
+        continue-on-error: true
+
+      - name: Re-sync context files
+        if: steps.drift.outcome == 'failure' || inputs.force_sync == true
+        run: npx @googlarz/agents-sync sync .
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          NO_COLOR: "1"
+
+      - name: Open PR with updated files
+        if: steps.drift.outcome == 'failure' || inputs.force_sync == true
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore: re-sync AI context files"
+          title: "chore: re-sync AI context files (agents-sync)"
+          body: |
+            Codebase drift detected. agents-sync has re-generated the AI context files.
+
+            **Files updated:**
+            - `AGENTS.md` — canonical source
+            - `CLAUDE.md` — Claude Code
+            - `.cursorrules` — Cursor
+            - `.github/copilot-instructions.md` — GitHub Copilot
+            - `GEMINI.md` — Gemini CLI
+            - `.windsurfrules` — Windsurf
+            - `.clinerules` — Cline
+
+            Review the diff and merge to keep your AI tools in sync.
+
+            > Generated by [agents-sync](https://github.com/googlarz/agents-sync)
+          branch: "agents-sync/update"
+          delete-branch: true
+          labels: "ai-context,automated"