Claude Code Templates & Starter Kit (CLAUDE.md, Skills, Settings & Hooks)

your-repo/
├── CLAUDE.md                                   # Always-on repo contract (80–150 lines)
├── AGENTS.md                                   # Cross-harness contract for Codex / OpenCode
├── .mcp.json                                   # Project-scoped MCP server definitions
└── .claude/
    ├── settings.json                           # Committed permissions + PreToolUse/PostToolUse hooks
    ├── settings.local.json                     # Gitignored personal overrides
    ├── skills/
    │   └── release-gate/
    │       ├── SKILL.md                        # Progressive-disclosure domain instructions
    │       └── scripts/verify-links.mjs        # Deterministic validator script
    ├── commands/
    │   └── ship.md                             # Explicit /ship operator workflow
    └── agents/
        └── code-reviewer.md                    # Isolated read-only verification subagent

# Project: Acme Web Platform

## Stack & commands
- Runtime: Node 22, Next.js 16 App Router, TypeScript strict, Tailwind CSS, Vitest
- Install: `pnpm install --frozen-lockfile`
- Type check: `pnpm run type-check`
- Unit tests: `pnpm test`
- Build gate: `pnpm run build`

## Architecture boundaries
- `app/` — Server Components by default; add `'use client'` at leaf interactive controls only
- `lib/db/` — Drizzle queries and schema migrations; all writes require Zod input validation
- `components/ui/` — Shared accessible primitives; preserve keyboard focus rings and ARIA labels

## Git & pull request protocol
- Create feature branches named `agent/<harness>/<scope>` from `origin/main`
- Run `pnpm run type-check && pnpm test` before every commit
- Never commit `.env*` files, API keys, or customer PII fixtures
- Keep edits surgical to the requested scope

{
  "permissions": {
    "allow": [
      "Bash(pnpm run type-check)",
      "Bash(pnpm test*)",
      "Bash(pnpm run lint*)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Read(.env)",
      "Read(.env.local)",
      "Read(.env.production)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/block-protected-files.mjs"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write --ignore-unknown \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env node
import fs from 'node:fs'

const payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}')
const filePath = String(payload?.tool_input?.file_path ?? '')
const protectedPatterns = [/^\.env($|\.)/, /^pnpm-lock\.yaml$/, /^migrations\/locked\//]

if (protectedPatterns.some((rx) => rx.test(filePath))) {
  process.stderr.write(`Blocked edit to protected path: ${filePath}. Ask human operator first.\n`)
  process.exit(2)
}

---
name: api-route-hardening
description: Enforce Zod request validation, rate-limit headers, structured error envelopes, and integration tests on Next.js Route Handlers. Use when creating or modifying files under app/api/.
---

# API route hardening

## Required checklist
1. Parse request body, query params, and headers through a strict `zod` schema before business logic.
2. Return consistent JSON error shapes: `{ error: { code: string, message: string, requestId: string } }`.
3. Enforce authentication and tenant authorization prior to any database read or mutation.
4. Set explicit `Cache-Control` headers (`no-store` on authenticated or mutating endpoints).
5. Add or update a `node:test` or `vitest` case covering `200`, `400` validation failure, and `401` unauthorized responses.

---
description: Run type-check, tests, diff audit, and open a draft pull request
---

Execute the pre-release verification sequence for the current branch:

1. Verify we are on a feature branch (`git branch --show-current` must differ from `main`).
2. Run `pnpm run type-check` and `pnpm test`. Stop immediately and fix any failure before continuing.
3. Inspect `git diff origin/main...HEAD` for unintended debug logs, secrets, or out-of-scope file edits.
4. Stage verified files, write a conventional commit message explaining the mechanism changed, push the branch, and open a draft pull request with test output attached.

---
name: code-reviewer
description: Independent read-only reviewer for pull request diffs, security boundaries, and test coverage.
tools: Read, Grep, Glob, Bash(git diff*), Bash(git log*)
---

You are an independent technical reviewer auditing the current branch diff against `origin/main`.

1. Check every modified route, database query, and external call for unhandled failure states, injection risks, or missing auth checks.
2. Verify tests exercise real system behavior against concrete fixtures and verifiable failure states.
3. Report findings with exact `file:line` references grouped into `Blocker` and `Improvement`, ending with `VERDICT: PASS` or `VERDICT: FAIL`.