Template Library

# Project: Node.js API

## Build & Run
- `npm run dev` — start dev server with hot reload
- `npm run build` — compile TypeScript to dist/
- `npm test` — run Jest test suite
- `npm run test:watch` — run tests in watch mode
- `npm run lint` — ESLint check
- `npm run typecheck` — tsc --noEmit

## Code Style
- TypeScript strict mode, no `any` types
- Use named exports, not default exports
- Import order: node builtins > external > internal > relative
- Error handling: always use custom AppError class from src/lib/errors.ts
- Naming: camelCase for variables/functions, PascalCase for types/classes

## Project Structure
- src/routes/ — route handlers grouped by resource
- src/services/ — business logic layer
- src/models/ — Prisma schema + generated types
- src/middleware/ — Express/Fastify middleware
- src/lib/ — shared utilities and helpers
- src/__tests__/ — test files mirror src/ structure

## Patterns
- All route handlers must use the asyncHandler wrapper
- Database access only through service layer, never in routes
- Validate request bodies with Zod schemas in src/schemas/
- Return consistent response format: { data, error, meta }

## Don't
- Don't use console.log — use the logger from src/lib/logger.ts
- Don't commit .env files or hardcode secrets
- Don't use synchronous file operations
- Don't skip input validation on any endpoint

# Project: React Frontend

## Build & Run
- `npm run dev` — Vite dev server on :5173
- `npm run build` — production build to dist/
- `npm run preview` — preview production build
- `npm run test` — Vitest
- `npm run lint` — ESLint + Prettier check
- `npm run typecheck` — tsc --noEmit

## Code Style
- TypeScript strict, no `any`
- Functional components only, no class components
- Use named exports for components
- CSS: Tailwind utility classes, no inline styles or CSS modules
- One component per file, filename matches component name

## Project Structure
- src/components/ui/ — reusable primitives (Button, Input, Card)
- src/components/features/ — feature-specific components
- src/components/layout/ — page layout components
- src/pages/ — route-level page components
- src/hooks/ — custom React hooks
- src/stores/ — Zustand stores
- src/lib/ — utilities, API client, constants
- src/types/ — shared TypeScript types

## Patterns
- State management: Zustand for global, useState for local
- Data fetching: TanStack Query with hooks in src/hooks/queries/
- Forms: React Hook Form + Zod validation
- All API calls go through src/lib/api-client.ts
- Use `cn()` helper from src/lib/utils for conditional classes

## Don't
- Don't use useEffect for data fetching — use TanStack Query
- Don't prop drill more than 2 levels — use Zustand or context
- Don't put business logic in components — extract to hooks
- Don't use index as key in lists with dynamic items

# Project: Python Data Science

## Environment
- Python 3.11+ with uv for package management
- `uv sync` — install dependencies
- `uv run pytest` — run tests
- `uv run ruff check .` — lint
- `uv run ruff format .` — format
- `uv run mypy src/` — type check

## Code Style
- Type hints on all function signatures
- Docstrings: Google style on all public functions
- Max line length: 88 (ruff default)
- Import order: stdlib > third-party > local (ruff handles this)
- Use pathlib.Path, not os.path

## Project Structure
- src/data/ — data loading and preprocessing
- src/features/ — feature engineering pipelines
- src/models/ — model training and evaluation
- src/utils/ — shared helpers
- notebooks/ — Jupyter notebooks (numbered: 01_, 02_)
- tests/ — pytest tests mirror src/ structure
- data/raw/ — original immutable data (gitignored)
- data/processed/ — cleaned datasets (gitignored)

## Patterns
- All data transformations are functions, not scripts
- Use sklearn Pipelines for ML workflows
- Config in src/config.py — no magic numbers in code
- Log experiments with MLflow
- Notebooks are for exploration only — production code goes in src/

## Don't
- Don't commit data files — use DVC or document download steps
- Don't use global state in data processing functions
- Don't use print() — use logging module
- Don't hardcode file paths — use config or CLI args

# Project: Full-Stack Monorepo

## Build & Run
- `pnpm install` — install all workspace dependencies
- `pnpm dev` — start all packages in dev mode (Turborepo)
- `pnpm build` — build all packages
- `pnpm test` — run tests across all packages
- `pnpm lint` — lint all packages
- `pnpm typecheck` — typecheck all packages

## Workspace Structure
- apps/web/ — Next.js frontend (App Router)
- apps/api/ — Express API server
- packages/shared/ — shared types, utils, and validation schemas
- packages/ui/ — shared React component library
- packages/config/ — shared ESLint, TS, Tailwind configs

## Code Style
- TypeScript strict everywhere
- Shared types go in packages/shared/src/types/
- Validation schemas in packages/shared/src/schemas/ (Zod)
- Import from packages using workspace aliases: @repo/shared, @repo/ui

## Patterns
- API routes return typed responses matching packages/shared types
- Frontend uses TanStack Query for all API calls
- End-to-end type safety: Zod schema → TS type → API → Frontend
- Database migrations in apps/api/prisma/
- Environment variables documented in each app's .env.example

## Don't
- Don't import from apps/* into packages/* (dependency direction)
- Don't duplicate types — single source of truth in packages/shared
- Don't use relative imports across workspace boundaries
- Don't add dependencies to the root package.json (use workspace)

# Project: React Native Mobile App

## Build & Run
- `npx expo start` — start Expo dev server
- `npx expo run:ios` — build and run on iOS simulator
- `npx expo run:android` — build and run on Android emulator
- `npm test` — run Jest tests
- `npm run lint` — ESLint check
- `npm run typecheck` — tsc --noEmit

## Code Style
- TypeScript strict mode
- Functional components with hooks only
- Use StyleSheet.create(), not inline styles
- Organize styles at bottom of component file
- Use rem-like spacing scale: 4, 8, 12, 16, 24, 32, 48

## Project Structure
- src/screens/ — screen components (one per route)
- src/components/ — reusable UI components
- src/navigation/ — React Navigation config and types
- src/hooks/ — custom hooks
- src/stores/ — Zustand stores
- src/services/ — API client, storage, notifications
- src/lib/ — utilities, constants, theme
- src/types/ — shared TypeScript types

## Patterns
- Navigation typing: use RootStackParamList from src/navigation/types
- API calls through src/services/api.ts (Axios instance)
- Async storage wrapper in src/services/storage.ts
- Theme colors from src/lib/theme.ts — never hardcode colors
- Handle safe areas with SafeAreaView or useSafeAreaInsets

## Don't
- Don't use ScrollView for long lists — use FlatList or FlashList
- Don't hardcode dimensions — use Dimensions API or percentages
- Don't store sensitive data in AsyncStorage — use SecureStore
- Don't use platform-specific code without Platform.select()

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)",
      "Bash(git *)",
      "Bash(pnpm *)",
      "Bash(yarn *)",
      "Bash(bun *)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(find *)",
      "Bash(grep *)",
      "Bash(curl *)",
      "mcp__*"
    ],
    "deny": []
  },
  "env": {
    "CLAUDE_CODE_EFFORT_LEVEL": "high"
  }
}

{
  "permissions": {
    "allow": [
      "Read(src/**)",
      "Read(docs/**)",
      "Read(package.json)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Write",
      "Bash(rm *)",
      "Bash(npm publish *)",
      "Bash(git push *)",
      "Bash(git reset *)",
      "Bash(curl *)",
      "mcp__*"
    ]
  },
  "env": {
    "CLAUDE_CODE_EFFORT_LEVEL": "medium"
  }
}

{
  "permissions": {
    "allow": [
      "Read",
      "Write(src/**)",
      "Write(tests/**)",
      "Bash(npm *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push origin HEAD)",
      "Bash(gh pr create *)",
      "Bash(gh pr comment *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "mcp__*"
    ]
  },
  "env": {
    "CLAUDE_CODE_EFFORT_LEVEL": "high",
    "MAX_THINKING_TOKENS": "16000"
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write "$CLAUDE_FILE_PATH"",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification "$CLAUDE_NOTIFICATION_MESSAGE" with title "Claude Code"'",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST -H 'Content-type: application/json' --data '{"text":"Claude Code completed a task: '"$CLAUDE_TASK_SUMMARY"'"}' https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

# Agent: Security Reviewer

## Role
You are a senior application security engineer performing a code review.

## Instructions
When reviewing code, check for these vulnerability categories in order:

1. **Injection** — SQL injection, XSS, command injection, LDAP injection
2. **Broken Authentication** — weak tokens, missing MFA logic, session fixation
3. **Sensitive Data Exposure** — secrets in code, PII in logs, missing encryption
4. **Broken Access Control** — missing auth checks, IDOR, privilege escalation
5. **Security Misconfiguration** — debug mode, default credentials, CORS issues
6. **Insecure Dependencies** — known CVEs, outdated packages

## Output Format
For each finding:
- **Severity**: Critical / High / Medium / Low
- **File**: path/to/file.ts:lineNumber
- **Issue**: One-sentence description
- **Evidence**: The vulnerable code snippet
- **Fix**: The corrected code snippet

## Constraints
- Only flag real issues, not theoretical ones
- Ignore style/formatting — focus purely on security
- If unsure about severity, explain your reasoning
- Always suggest a fix, not just the problem

# Agent: Test Writer

## Role
You are a senior QA engineer who writes thorough, maintainable tests.

## Instructions
When given code to test:

1. **Read** the source file and all its imports to understand the full interface
2. **Identify** the testing framework already in use (check package.json or existing tests)
3. **Write** tests covering:
   - Happy path (expected inputs produce expected outputs)
   - Edge cases (empty, null, undefined, boundary values)
   - Error handling (invalid inputs, thrown exceptions)
   - Integration points (mocked external dependencies)

## Output Format
- One test file per source file
- Use describe/it blocks with descriptive names
- Group tests by method or behavior
- Include setup/teardown when needed

## Constraints
- Match existing test patterns in the codebase
- Mock external dependencies, don't make real API calls
- Use factories or fixtures for test data, not inline objects
- Each test should be independent — no shared mutable state
- Test behavior, not implementation details
- Aim for >90% branch coverage

# Agent: Documentation Generator

## Role
You are a technical writer who creates clear, developer-friendly documentation.

## Instructions
When asked to document code:

1. **Read** the source files and existing documentation
2. **Identify** public APIs, exported functions, types, and components
3. **Generate** documentation including:
   - Overview (what it does, when to use it)
   - Installation/setup steps
   - API reference with types and parameters
   - Usage examples (simple → advanced)
   - Common pitfalls and FAQ

## Output Format
- Use Markdown with proper heading hierarchy
- Code examples in fenced blocks with language tags
- Tables for parameter/return value documentation
- Callout blocks for warnings and tips

## Constraints
- Write for the audience: assume they know the language, not the library
- Every public function needs at least one usage example
- Keep explanations concise — prefer examples over prose
- Use the project's existing documentation style if present
- Don't document private/internal functions unless asked

# /fix-issue

Fetch the GitHub issue #$ARGUMENTS from this repository.

Steps:
1. Read the issue title, description, and any comments using `gh issue view`
2. Understand the bug or feature request
3. Find the relevant code in the repository
4. Implement the fix or feature
5. Write or update tests to cover the change
6. Run the test suite to verify nothing is broken
7. Create a commit with a conventional commit message referencing the issue
8. Summarize what you changed and why

Constraints:
- Follow existing code patterns and style
- Don't modify unrelated files
- Keep the change minimal and focused
- If the issue is ambiguous, explain your interpretation before coding

# /deploy

Run the full deployment pipeline for this project.

Steps:
1. Run `git status` to check for uncommitted changes — abort if dirty
2. Run the full test suite: `npm test`
3. Run the linter: `npm run lint`
4. Run type checking: `npm run typecheck`
5. Build the project: `npm run build`
6. If all checks pass, show a summary of what will be deployed:
   - Current branch and latest commit
   - Number of commits ahead of main
   - List of changed files since last deploy tag
7. Ask for confirmation before proceeding
8. If confirmed: push to the deployment branch and create a deploy tag

Constraints:
- Never force push
- Never deploy from a branch other than main unless explicitly asked
- If any check fails, stop immediately and report the failure
- Log all commands and their output for debugging

# /review-pr

Review the pull request at $ARGUMENTS (URL or number).

Steps:
1. Fetch the PR details using `gh pr view`
2. Read the full diff using `gh pr diff`
3. Check if the PR description explains the changes adequately
4. Review each changed file for:
   - **Correctness**: Does the code do what the PR claims?
   - **Security**: Any new vulnerabilities introduced?
   - **Performance**: Any regressions or missed optimizations?
   - **Testing**: Are changes adequately covered by tests?
   - **Style**: Does it follow the project's conventions?
5. Check if CI checks are passing using `gh pr checks`
6. Provide a structured review summary

Output format:
## Summary
[1-2 sentence overview]

## Blockers
[Issues that must be fixed before merge]

## Suggestions
[Improvements that would be nice but aren't blocking]

## Nits
[Minor style/preference items]

## Verdict
[Approve / Request Changes / Needs Discussion]