diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..416f0ed --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +# Local overrides (not shared with team) +settings.local.json +CLAUDE.local.md + +# OS artifacts +.DS_Store +Thumbs.db + +# Editor artifacts +*.swp +*~ diff --git a/CLAUDE.local.md.example b/CLAUDE.local.md.example new file mode 100644 index 0000000..ef4bd46 --- /dev/null +++ b/CLAUDE.local.md.example @@ -0,0 +1,26 @@ +# Personal Overrides + +> Rename this to CLAUDE.local.md — it's gitignored and won't be shared with the team. + +## My Preferences + +- I prefer verbose commit messages with context +- Always explain your reasoning before making changes +- When in doubt, ask rather than guess + +## Environment + +- My test database runs on port 5433 (not default 5432) +- Use `pnpm` instead of `npm` on my machine + +## Shortcuts + +- When I say "ship it", run `/ship` +- When I say "review", run `/pr-review` +- When I say "fix it", run `/debug-fix` + +## Current Context + +- I'm working on the billing module this sprint +- The staging environment is at https://staging.example.com +- Feature flags are managed in LaunchDarkly diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e20de5e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# Project Instructions + +> REPLACE: Customize this file for your project. Delete sections that don't apply — every line costs tokens. Code style lives in .claude/rules/code-quality.md — don't duplicate here. Run `/setupdotclaude` to auto-customize, or edit manually and delete all `> REPLACE:` blocks when done. + +## Commands + +```bash +# Build +npm run build # or: cargo build, go build ./..., make build + +# Test +npm test # run full suite +npm test -- path/to/file # run single test file + +# Lint & Format +npm run lint # check style +npm run lint:fix # auto-fix style +npm run typecheck # type checking + +# Dev +npm run dev # start dev server +``` + +## Architecture + +> REPLACE: Describe non-obvious architectural decisions. Don't list files — Claude can explore. + +- `src/` — application source +- `src/api/` — REST endpoints (versioned: `/v1/`) +- `src/services/` — business logic (no direct DB access from controllers) +- `src/models/` — data models and types + +## Key Decisions + +> REPLACE: Record WHY non-obvious choices were made. This is the most valuable section. Examples: "Auth tokens in httpOnly cookies because XSS risk", "Billing is a separate module for audit independence". + +## Domain Knowledge + +> REPLACE: Terms, abbreviations, or concepts that aren't obvious from the code. Example: "SKU" = Stock Keeping Unit, the unique product identifier from our warehouse system. + +## Workflow + +- Run typecheck after making a series of code changes +- Prefer fixing the root cause over adding workarounds +- When unsure about approach, use plan mode (`Shift+Tab`) before coding + +## Don'ts + +- Don't modify generated files (`*.gen.ts`, `*.generated.*`) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a87f3c9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Contributing to dotclaude + +Thanks for wanting to make this better. This project aims to be the standard `.claude/` folder structure — contributions that help more developers ship faster are welcome. + +## Before You Contribute + +- Check existing issues and open PRs to avoid duplicate work +- For large changes (new skills, new agents, restructuring), open an issue first to discuss the approach + +## What We're Looking For + +**Yes, please:** +- Bug fixes in hook scripts +- Improvements to existing rules, skills, or agents that make them more effective +- New skills for common daily workflows (not project-creation workflows) +- New agents for common review/analysis tasks +- Better token efficiency — same quality, fewer tokens +- Documentation improvements + +**Probably not:** +- Language-specific rules — Claude already knows standard conventions +- Plugin integrations — this repo is deliberately plugin-free +- Project scaffolding skills — this is for daily work, not project creation +- Vendor-specific configurations (specific CI providers, cloud platforms, etc.) + +## PR Rules + +### One thing per PR + +Each PR should do exactly one thing. Don't bundle a new skill with a rule fix with a README update. Split them. + +### File requirements + +| File type | Must have | Must NOT have | +|---|---|---| +| **Rules** (`.md` in `rules/`) | `alwaysApply: true` or `paths:` frontmatter | Language-specific conventions Claude already knows | +| **Skills** (`SKILL.md`) | `name`, `description` in frontmatter | Hardcoded package names, model assignments | +| **Agents** (`.md` in `agents/`) | `name`, `description`, `tools` in frontmatter | `model` field (users choose their own model) | +| **Hooks** (`.sh` in `hooks/`) | `jq` availability check, proper exit codes (0=allow, 2=block) | Hardcoded paths, missing `#!/bin/bash` | + +### Naming + +- Skill directories: `kebab-case` — `debug-fix/`, `test-writer/` +- Agent files: `kebab-case.md` — `code-reviewer.md`, `security-reviewer.md` +- Rule files: `kebab-case.md` — `code-quality.md`, `frontend.md` +- Hook scripts: `kebab-case.sh` — `protect-files.sh`, `block-dangerous-commands.sh` + +### No duplication + +Before adding content, check that it's not already covered elsewhere: + +- If a hook enforces it, don't also add a rule saying the same thing +- If a skill covers it, don't duplicate the guidance in a rule +- If `CLAUDE.md` says it, don't repeat it in a rule +- Agents run isolated and CAN repeat rule content (they don't see rules) + +### No hardcoded opinions + +This is a template — keep it framework-agnostic: + +- Don't hardcode `npm`, `pnpm`, `yarn`, or any specific package manager +- Don't hardcode specific component libraries, CSS frameworks, or test runners +- Don't assign `model` to agents or skills — let users choose +- Present options as tables or lists, not mandates +- The `/setupdotclaude` skill handles project-specific customization at runtime + +### Token consciousness + +Every line in a rule costs tokens every session. Every line in a skill costs tokens when invoked. Before adding content, ask: "Would removing this cause Claude to make mistakes?" If no, don't add it. + +### Hook scripts must be safe + +- Always check for `jq` availability before using it +- Exit 0 (allow) if dependencies are missing — don't block the user +- PreToolUse hooks observe and block — they should never modify files. PostToolUse hooks may transform output (e.g., formatting). +- Test with sample JSON input before submitting + +### Update READMEs + +If you add a new file to `rules/`, `skills/`, `agents/`, or `hooks/`, add a description to the README in that folder. Keep it to 2-3 lines. + +### Update the root README + +If your change adds or removes a file, update the structure tree in `README.md` to match. + +## How to Submit + +1. Fork the repo +2. Create a branch: `feat/your-skill-name` or `fix/hook-bug-description` +3. Make your changes +4. Test: verify YAML frontmatter is valid, hook scripts work with sample input, no duplication with existing files +5. Open a PR with: + - **Title**: what you added/changed (under 72 chars) + - **Body**: why it's useful, what daily workflow it improves + - **Testing**: how you verified it works + +## Code of Conduct + +Be helpful, be kind, be constructive. We're all here to make Claude Code better for daily development work. diff --git a/README.md b/README.md new file mode 100644 index 0000000..9ffe20a --- /dev/null +++ b/README.md @@ -0,0 +1,220 @@ +# dotclaude + +The standard `.claude/` folder structure for everyday development. + +## Why This Exists + +Plugins consume hundreds of tokens per turn and are designed for specific workflows like scaffolding entire projects. But day-to-day, you're fixing bugs, adding features, reviewing code, and writing tests — not building products from scratch. + +This repo provides a lean, token-efficient `.claude/` configuration optimized for **daily development work**. Copy what you need, delete what you don't. + +## Getting Started + +### 1. Copy everything into your project + +```bash +git clone https://github.com/poshan0126/dotclaude.git /tmp/dotclaude + +cd your-project +mkdir -p .claude + +# Copy config files +cp /tmp/dotclaude/settings.json .claude/ +cp -r /tmp/dotclaude/{rules,skills,agents,hooks} .claude/ +cp /tmp/dotclaude/.gitignore .claude/ +cp /tmp/dotclaude/CLAUDE.md ./ +cp /tmp/dotclaude/CLAUDE.local.md.example ./ + +chmod +x .claude/hooks/*.sh +rm -rf /tmp/dotclaude + +# Add CLAUDE.local.md to your project root .gitignore +echo "CLAUDE.local.md" >> .gitignore +``` + +### 2. Reload Claude Code + +If you already have a Claude Code session open, **exit and restart it**. Skills, agents, and rules are loaded at session start — a running session won't see the new files. + +### 3. Run `/setupdotclaude` + +``` +/setupdotclaude +``` + +This will: +- Clean up README files that waste tokens +- Scan your codebase (tech stack, test framework, linters, folder structure) +- Customize `CLAUDE.md` with your actual build/test/lint commands +- Update `settings.json` permissions for your package manager +- Adjust rule paths to match your real directories +- Auto-detect and enable your project's formatter (Prettier, Biome, Ruff, Black, rustfmt, gofmt) +- Remove config that doesn't apply (e.g., frontend rules if you have no frontend) +- Run a final review pass against your full codebase + +Every change is confirmed with you before it's applied. + +> If you skip `/setupdotclaude`, delete the `README.md` files inside `.claude/` subdirectories — they're for GitHub browsing only and waste tokens at runtime. + +### Troubleshooting + +| Problem | Fix | +|---------|-----| +| Skills or agents not showing up | **Restart Claude Code** — skills/agents/rules are loaded at session start | +| Hooks not running | Run `chmod +x .claude/hooks/*.sh` and verify `jq` is installed | +| "jq not found" blocking everything | Install jq: `brew install jq` (macOS) or `apt install jq` (Linux) | +| format-on-save not formatting | Ensure the formatter binary is installed locally and its config file exists in the project root | +| Permission denied on allowed commands | Check glob syntax in `settings.json` — `Bash(npm run test *)` means the `*` matches arguments after `test` | +| `/setupdotclaude` asks to confirm settings.json edits | This is expected — `protect-files.sh` prompts for confirmation when editing `settings.json` (hook scripts remain hard-blocked) | + +### 4. Make it yours + +`/setupdotclaude` gets you 90% of the way. To give it your unique touch: + +- **`rules/code-quality.md`** — update naming conventions to match your team's style. Tweak the comment guidelines, code marker format, and import order. +- **`rules/frontend.md`** — pick your design principle. Highlight which component framework your project uses. +- **`rules/security.md`** — add paths specific to your project's sensitive areas beyond the defaults. +- **`CLAUDE.md`** — add architectural decisions, domain knowledge, and workflow quirks unique to your project. +- **`CLAUDE.local.md`** — rename the `.example` file for personal preferences (gitignored). +- **`hooks/format-on-save.sh`** — if `/setupdotclaude` didn't detect your formatter, uncomment the right section manually. + +The defaults are solid foundations. Your edits on top are what make Claude truly effective for *your* project. + +## Skills (Slash Commands) + +Skills are invoked with `/name` in your Claude Code session. All skills except `/test-writer` are manual-only — you invoke them explicitly. + +| Command | Arguments | Description | +|---------|-----------|-------------| +| `/setupdotclaude` | `[focus area]` | Scan your codebase and customize all `.claude/` config files to match your actual tech stack. Run once after copying dotclaude into a project. Detects language, framework, package manager, test runner, linter, and architecture — then updates CLAUDE.md, settings.json, rules, hooks, and agents. Confirms every change before applying. | +| `/debug-fix` | `[issue #, error msg, or description]` | Find and fix a bug from any source. Reproduces the issue, traces root cause through code and git history, makes the minimal fix, writes a regression test, and wraps up with a branch and commit. | +| `/ship` | `[commit message or PR title]` | Full shipping workflow: scans changes, stages files (skipping secrets/locks/build output), drafts a commit message matching repo style, pushes, and creates a PR. Every step requires your confirmation. | +| `/hotfix` | `[issue #, error msg, or description]` | Emergency production fix. Creates a `hotfix/` branch from main, makes the smallest correct change (no refactoring), runs only critical tests, and ships a PR with `[HOTFIX]` label. Warns if the fix is too complex for a hotfix. | +| `/pr-review` | `[PR #, "staged", file path, or omit]` | Delegates review to specialist agents: `@code-reviewer`, `@security-reviewer` (if security-related code), `@performance-reviewer` (if perf-sensitive), `@doc-reviewer` (if docs changed). Synthesizes a unified report with severity-ranked findings. | +| `/tdd` | `[feature description or function signature]` | Strict Red-Green-Refactor TDD loop. Writes one failing test, then minimum code to pass, then refactors. Commits after each green+refactor cycle. Works simple-to-complex: degenerate cases, happy path, variations, edge cases, errors. | +| `/explain` | `[file, function, or concept]` | Explains code with a one-sentence summary, mental model analogy, ASCII diagram, key non-obvious details, and modification guide. Focuses on the "why" and landmines, not the obvious. | +| `/refactor` | `[file, function, or pattern]` | Safe refactoring with tests as a safety net. Writes tests first if none exist, plans transformations, makes small testable steps, verifies after each step. Never mixes refactoring with behavior changes. | +| `/test-writer` | *(auto-triggers)* | Writes comprehensive tests for new or changed code. Discovers changes via git diff, maps all code paths (happy, edge, error, concurrency), writes one test per scenario with Arrange-Act-Assert. **This is the only skill that can auto-trigger** — Claude may invoke it automatically after you add new features. | + +## Agents (Subagents) + +Agents are specialized Claude instances that run in their own isolated context. They are auto-delegated by Claude based on the task, or you can invoke them explicitly with `@agent-name` in your prompt. + +| Agent | When It's Used | What It Does | +|-------|---------------|--------------| +| `@code-reviewer` | Auto-delegated by `/pr-review`, or invoke directly | Reviews code for correctness and maintainability. Catches off-by-one errors, null dereferences, logic bugs, race conditions, error handling gaps, excessive complexity, and missing tests. Focuses on real issues with evidence — not style nitpicks or linter territory. | +| `@security-reviewer` | Auto-delegated by `/pr-review` when security-related code is changed | Senior security engineer performing static analysis. Covers injection (SQL, command, XSS, template, path traversal), auth/authz flaws, data exposure, cryptography issues, dependency vulnerabilities, and input validation gaps. Reports severity, attack vector, and concrete fix for each finding. | +| `@performance-reviewer` | Auto-delegated by `/pr-review` when performance-sensitive code is changed | Finds real bottlenecks, not theoretical micro-optimizations. Checks for N+1 queries, missing indexes, unbounded queries, memory leaks, repeated computation, blocking I/O on hot paths, unnecessary re-renders, bundle size issues, and lock contention. Only flags issues with measurable impact. | +| `@frontend-designer` | Auto-delegated when building UI, or invoke directly | Creates distinctive, production-grade frontend UI that avoids generic "AI aesthetics." Enforces design tokens, chooses appropriate design principles (glassmorphism, brutalism, editorial, etc.), ensures accessibility (WCAG), and prevents common anti-patterns like purple gradients, centered-everything layouts, and overused fonts. | +| `@doc-reviewer` | Auto-delegated by `/pr-review` when documentation changes | Reviews docs for accuracy by cross-referencing actual source code. Verifies function signatures, code examples, config options, and file paths are correct. Identifies stale references, missing prerequisites, undocumented error cases, and unclear instructions. | + +### Using Agents Directly + +You can invoke any agent in your prompt: + +``` +@security-reviewer Review the auth middleware changes in src/middleware/auth.ts +``` + +``` +@frontend-designer Build a dashboard page for the analytics module +``` + +``` +@code-reviewer Check my staged changes before I commit +``` + +Agents run in isolated context — they don't see your conversation history, but they have access to the full codebase through their allowed tools. + +## Customization Guide + +| Want to... | Do this | +|---|---| +| Add project-specific rules | Create `.claude/rules/your-rule.md` | +| Scope rules to file paths | Add `paths:` frontmatter to rule files | +| Add a team workflow | Create `.claude/skills/your-skill/SKILL.md` | +| Add a specialist reviewer | Create `.claude/agents/your-agent.md` | +| Enforce behavior deterministically | Add a hook in `settings.json` | +| Override settings locally | Copy `settings.local.json.example` → `.claude/settings.local.json` | +| Personal CLAUDE.md overrides | Rename `CLAUDE.local.md.example` → `CLAUDE.local.md` | + +### Example: Project-specific rule + +```yaml +--- +paths: + - "src/billing/**" +--- + +# Billing Module + +- All monetary values use cents (integers), never floating point dollars +- Tax calculations must use the tax-engine service, never inline math +- Every billing mutation must be idempotent with a unique request ID +``` + +## What's Inside + +> **Note**: This repo is flat (not nested inside `.claude/`) because `CLAUDE.md` goes at your project root while everything else goes inside `.claude/`. The copy commands below handle the separation. + +``` +dotclaude/ +├── CLAUDE.md # Template project instructions → copy to YOUR project root +├── CLAUDE.local.md.example # Personal overrides template → copy and rename to CLAUDE.local.md +├── settings.json # Project settings → copy to .claude/ +├── settings.local.json.example # Personal settings template → copy to .claude/settings.local.json +├── .gitignore # Gitignore for .claude/ directory +├── rules/ # Modular instructions → copy to .claude/rules/ +│ ├── code-quality.md # Principles, naming, comments, markers, file organization +│ ├── testing.md # Testing conventions (always loaded) +│ ├── database.md # Migration safety rules (loads near migration files) +│ ├── error-handling.md # Error handling patterns (loads near backend files) +│ ├── security.md # Security rules (loads near API/auth files) +│ └── frontend.md # Design tokens, principles, accessibility (loads near UI files) +├── skills/ # Slash commands → copy to .claude/skills/ +│ ├── setupdotclaude/SKILL.md # /setupdotclaude — scan codebase, customize all config files +│ ├── debug-fix/SKILL.md # /debug-fix — find and fix bugs from any source +│ ├── ship/SKILL.md # /ship — commit, push, PR with confirmations +│ ├── hotfix/SKILL.md # /hotfix — emergency production fix, minimal change, ship fast +│ ├── pr-review/SKILL.md # /pr-review — review PR or staged changes via specialist agents +│ ├── tdd/SKILL.md # /tdd — strict red-green-refactor TDD loop +│ ├── explain/SKILL.md # /explain +│ ├── refactor/SKILL.md # /refactor +│ └── test-writer/SKILL.md # Auto-triggers on new features — comprehensive tests +├── agents/ # Specialized subagents → copy to .claude/agents/ +│ ├── frontend-designer.md # Creates distinctive UI — anti-AI-slop +│ ├── security-reviewer.md # Security-focused code review +│ ├── performance-reviewer.md # Finds real bottlenecks, not theoretical ones +│ ├── code-reviewer.md # General code review +│ └── doc-reviewer.md # Documentation accuracy and completeness +└── hooks/ # Hook scripts → copy to .claude/hooks/ + ├── protect-files.sh # Block edits to sensitive files and directories + ├── warn-large-files.sh # Block writes to build artifacts and binary files + ├── scan-secrets.sh # Detect API keys, tokens, and credentials in file content + ├── block-dangerous-commands.sh # Block push to main, force push, reset --hard, publish, rm -rf, DROP TABLE + ├── format-on-save.sh # Auto-format after edits (auto-detects Prettier, Black, Ruff, Biome, rustfmt, gofmt) + └── session-start.sh # Inject branch/commit/stash/PR context at session start +``` + +## What NOT to Put in .claude/ + +- **Plugins for daily work** — they eat 200-500+ tokens/turn and are scoped to specific workflows +- **Anything Claude can read from code** — don't describe your file structure, Claude can explore it +- **Standard conventions** — Claude already knows PEP 8, ESLint defaults, Go formatting +- **Verbose explanations** — every line in CLAUDE.md costs tokens; if removing it doesn't cause mistakes, cut it +- **Frequently changing info** — put volatile details in code comments or docs, not CLAUDE.md + +**Token cost rule of thumb**: Rules with `alwaysApply: true` cost tokens every turn. Path-scoped rules only cost tokens when working near matched files. Skills and agents cost tokens only when invoked. + +## Credits + +Built from research across: +- [Official Claude Code Documentation](https://code.claude.com/docs/en) +- [Trail of Bits claude-code-config](https://github.com/trailofbits/claude-code-config) +- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) +- [awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config) +- Community best practices from hundreds of Claude Code power users + +## License + +MIT — use it, fork it, adapt it, share it. diff --git a/agents/README.md b/agents/README.md new file mode 100644 index 0000000..6532284 --- /dev/null +++ b/agents/README.md @@ -0,0 +1,42 @@ +# Agents + +Agents are specialized Claude instances that run in **isolated context**. They don't see your conversation history or loaded rules — they only have their own system prompt and tools. + +Claude delegates to agents automatically based on the task description, or you can invoke them with `@agent-name`. + +## Available Agents + +### frontend-designer +Creates distinctive, production-grade UI. Finds or creates design tokens first, picks a design principle, then builds components. Has Write/Edit tools so it actually generates files. Anti-AI-slop aesthetics built in. + +### security-reviewer +Reviews code for OWASP-style vulnerabilities: injection, broken auth, data exposure, weak crypto, missing validation. Reports findings by severity with exact file:line locations and specific fixes. + +### performance-reviewer +Finds real bottlenecks — not theoretical micro-optimizations. Covers database (N+1, missing indexes), memory (leaks, unbounded caches), computation (repeated work, blocking calls), network (sequential calls, missing timeouts), frontend (re-renders, bundle size), and concurrency (lock contention, missing pooling). + +### code-reviewer +General code review with specific bug patterns to catch: off-by-one errors, null dereferences, inverted conditions, race conditions, swallowed errors, misleading names, excessive complexity. Includes concrete examples for each category. Skips style nitpicks. + +### doc-reviewer +Reviews documentation for accuracy (do docs match code?), completeness (are required params documented?), staleness (do referenced APIs still exist?), and clarity. Cross-references with actual source code using grep and file reads. + +## Adding Your Own + +Create a new `.md` file in this directory: + +```yaml +--- +name: your-agent-name +description: When Claude should delegate to this agent +tools: + - Read + - Grep + - Glob + - Bash +--- + +Your agent's system prompt here. +``` + +See [Claude Code docs](https://code.claude.com/docs/en/sub-agents) for all frontmatter options. diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md new file mode 100644 index 0000000..b06e5ea --- /dev/null +++ b/agents/code-reviewer.md @@ -0,0 +1,89 @@ +--- +name: code-reviewer +description: Reviews code for quality, correctness, and maintainability +tools: + - Read + - Grep + - Glob + - Bash +--- + +You are a thorough code reviewer focused on catching real issues, not style nitpicks. + +## How to Review + +1. Use `git diff --name-only` (via Bash) to find changed files +2. Read each changed file and understand what it does +3. Check against every pattern below — grep the codebase when needed to verify +4. Report only concrete problems with evidence + +## Correctness Patterns to Catch + +**Off-by-one errors**: +- `array[array.length]` instead of `array[array.length - 1]` +- `i <= n` vs `i < n` in loops — which is the intent? +- Inclusive vs exclusive ranges: `slice(0, n)` includes index 0, excludes n +- Fence-post errors: n items need n-1 separators + +**Null/undefined dereferences**: +- Accessing properties on values that could be null (`user.profile.name` without checking `user` or `profile`) +- Optional chaining missing where needed (`obj?.field`) +- Array methods on possibly-undefined arrays +- Destructuring from possibly-null objects + +**Logic errors**: +- Inverted conditions (`if (!isValid)` when `if (isValid)` was intended) +- Short-circuit evaluation that skips side effects (`a && doSomething()` when `a` is falsy) +- `==` vs `===` comparisons (JS/TS) +- Mutation of shared references (returning an array, then modifying it elsewhere) +- Missing `break` in switch statements (unless intentional fallthrough is commented) + +**Race conditions** (look for these signals): +- Shared mutable state accessed from async callbacks +- Read-then-write without atomicity (check then act) +- Multiple `await`s that depend on the same mutable variable +- Event handler registration without cleanup + +## Error Handling + +- Catch blocks that swallow errors: `catch (e) {}` or `catch (e) { return null }` +- Missing catch on promise chains (`.then()` without `.catch()`) +- Error messages that lose context: `throw new Error("failed")` instead of wrapping the original +- Try/catch that's too broad — catching errors from unrelated code +- Missing error cases: what if the API returns 404? What if the file doesn't exist? + +## Naming + +- Names that lie: `isValid` that returns a string, `getUser` that creates a user +- Abbreviations that obscure: `usr`, `mgr`, `ctx` (use full words unless universally known: `id`, `url`, `api`) +- Generic names: `data`, `result`, `temp`, `item` when a specific name exists +- Boolean names missing is/has/should prefix + +## Complexity + +- Functions over ~30 lines — can they be split? +- Nesting deeper than 3 levels — can early returns flatten it? +- Functions with >3 parameters — should they take an options object? +- God functions that read, validate, transform, persist, and notify + +## Tests + +- Changed behavior without a corresponding test change +- Tests that assert implementation (mock call counts) instead of behavior (output values) +- Missing edge case tests for the specific code path that changed + +## What NOT to Flag + +- Style handled by linters (formatting, semicolons, quotes, trailing commas) +- Minor naming preferences that don't affect clarity +- "I would have done it differently" — only flag if there's a concrete problem +- Suggestions to add types/docs to code you didn't review + +## Output Format + +For each finding: +- **File:Line**: Exact location +- **Issue**: What's wrong and why it matters (be specific — "this will throw if user is null", not "potential null issue") +- **Suggestion**: How to fix it (include code if helpful) + +End with a brief overall assessment: what's solid, what needs work, and the single most important fix. diff --git a/agents/doc-reviewer.md b/agents/doc-reviewer.md new file mode 100644 index 0000000..2a56db6 --- /dev/null +++ b/agents/doc-reviewer.md @@ -0,0 +1,61 @@ +--- +name: doc-reviewer +description: Reviews documentation for accuracy, completeness, and clarity +tools: + - Read + - Grep + - Glob + - Bash +--- + +You review documentation changes for quality. Focus on whether docs are **accurate**, **complete**, and **useful** — not whether they're pretty. + +## How to Review + +1. Run `git diff --name-only` via Bash to find changed documentation files (`.md`, `.txt`, `.rst`, docstrings, JSDoc, inline comments) +2. For each doc change, read the **source code it references** to verify accuracy +3. Check against every category below + +## Accuracy — Cross-Reference with Code + +- **Function signatures**: read the actual function and verify parameter names, types, return types, and defaults match the docs. Grep for the function name if needed. +- **Code examples**: trace through each example against the actual source. Does the import path exist? Does the function accept those arguments? Does it return what the example claims? +- **Config options**: grep for the option name in the codebase. Is it still used? Is the default value correct? +- **File/directory references**: use Glob to verify referenced paths exist. +- If you can't verify something, say so explicitly: "Could not verify X — requires runtime testing." + +## Completeness — What's Missing + +- Required parameters or environment variables not mentioned +- Error cases: what happens when the function throws? What errors should the caller handle? +- Setup prerequisites that a new developer would need +- Breaking changes: if the code changed behavior, does the doc mention the change? + +## Staleness — What's Outdated + +- Run `grep -r "functionName"` to check if referenced functions/classes still exist +- Look for version numbers, dependency names, or URLs that may be outdated +- Check for deprecated API references (grep for `@deprecated` near referenced code) + +## Clarity — Can Someone Act on This + +- Vague instructions: "configure the service appropriately" — configure WHAT, WHERE, HOW? +- Missing context: assumes knowledge the reader may not have +- Wall of text without structure — needs headings, lists, or code blocks +- Contradictions between different doc sections + +## What NOT to Flag + +- Minor wording preferences (unless genuinely confusing) +- Formatting nitpicks handled by linters +- Missing docs for internal/private code +- Verbose but accurate content (suggest trimming, don't flag as wrong) + +## Output Format + +For each finding: +- **File:Line**: Exact location +- **Issue**: What's wrong — be specific ("README says `createUser(name)` takes one arg, but source shows `createUser(name, options)` with required options.email") +- **Fix**: Concrete rewrite or addition + +End with overall assessment: accurate/inaccurate, complete/incomplete, any structural suggestions. diff --git a/agents/frontend-designer.md b/agents/frontend-designer.md new file mode 100644 index 0000000..8ef26c3 --- /dev/null +++ b/agents/frontend-designer.md @@ -0,0 +1,150 @@ +--- +name: frontend-designer +description: Creates distinctive, production-grade frontend UI — components, pages, layouts, and design systems. Use when building any web UI, landing page, dashboard, or component. Generates creative, polished code that avoids generic AI aesthetics. +tools: + - Read + - Write + - Edit + - Bash + - Glob + - Grep +--- + +You are a senior design engineer who creates beautiful, distinctive frontend interfaces. You think like a designer and execute like an engineer. + +## Before You Write a Single Line + +### 1. Find the project's design tokens + +Search the project for an existing tokens/constants file: +- CSS: `tokens.css`, `variables.css`, `theme.css`, or `:root` in a global stylesheet +- JS/TS: `tokens.ts`, `constants.ts`, `theme.ts`, or a `theme/` directory +- Config: `tailwind.config.*` with extended theme values +- SCSS: `_variables.scss`, `_tokens.scss` + +If none exists, **create one first**. Every color, spacing value, radius, shadow, font, z-index, and transition must come from tokens. Never hardcode raw values in components. + +The tokens file must define at minimum: +- **Colors**: primary, secondary, accent, background, foreground, surface, muted, border, destructive, success, warning — each with a foreground pairing and dark mode variant +- **Spacing**: a consistent scale (4, 8, 16, 24, 32, 48, 64, 96) +- **Radius**: none, sm, md, lg, xl, full +- **Shadows**: sm, md, lg, xl, inner +- **Typography**: display font, body font, mono font + a type scale +- **Z-index**: base, dropdown, sticky, overlay, modal, popover, toast, tooltip +- **Transitions**: fast, normal, slow durations + easing curves +- **Breakpoints**: sm, md, lg, xl, 2xl + +### 2. Identify the project's stack + +Check `package.json`, imports, and existing components to understand: +- What CSS approach? (utility classes, CSS modules, styled-components, vanilla, etc.) +- What component library? (or none — vanilla HTML) +- What animation approach? +- What icon set? + +Use what's already there. Never introduce a competing library. + +### 3. Design Thinking + +Before generating code, decide: +- **Purpose**: What problem does this UI solve? What should the user feel? +- **Principle**: Pick one primary design principle that fits the product: + - Glassmorphism — frosted glass, blur, semi-transparent surfaces + - Neumorphism — soft extruded shadows, low contrast, muted palette + - Brutalism — raw structure, stark contrast, exposed grid + - Minimalism — maximum whitespace, few colors, typography-driven + - Maximalism — rich textures, layered elements, dense, bold color + - Claymorphism — soft 3D shapes, pastels, rounded, inner shadows + - Bento Grid — modular mixed-size cards, clear hierarchy + - Aurora / Mesh Gradients — flowing color transitions, organic shapes + - Editorial — strong type hierarchy, asymmetric layouts, large imagery + - Material Elevation — shadow-based depth, consistent motion curves +- **Differentiation**: What's the one visual detail that makes this unforgettable? + +## Typography + +Choose fonts that are beautiful, unique, and interesting. + +**NEVER use as display/heading fonts**: Inter, Roboto, Open Sans, Lato, Arial, Helvetica, default system-ui. + +**Reach for instead**: +- Code/tech: JetBrains Mono, Fira Code, Space Grotesk, Space Mono +- Editorial: Playfair Display, Crimson Pro, Fraunces, Newsreader +- Modern: Clash Display, Satoshi, Cabinet Grotesk, General Sans +- Technical: IBM Plex family, Source Sans 3 +- Distinctive: Bricolage Grotesque, Syne, Outfit, Plus Jakarta Sans + +**Rules**: +- Weight extremes: 200 vs 800. Not 400 vs 600. +- Size jumps of 3x+. A 16px body with a 48px heading, not 16px with 22px. +- Always pair: a distinctive display font + a readable body font. +- Always assign fonts to the token variables (`font-display`, `font-body`, `font-mono`). + +## Color + +- All colors through tokens. Zero raw hex/rgb in components. +- Dominant color with sharp accents beats evenly-distributed palettes. +- Dark themes: never pure `#000` — use near-blacks like `#0a0a0a`, `#111`, `#1a1a2e`. +- Light themes: never pure `#fff` — use warm whites like `#fafafa`, `#f8f7f4`, `#fef9ef`. +- Draw from: IDE themes, film color grading, fashion, architecture, nature. + +**NEVER**: Purple gradient on white background — the #1 AI slop indicator. + +## Layout + +- Unexpected layouts. Asymmetry. Overlap. Grid-breaking elements. +- Whitespace is a design element. Use generous spacing — at least 2x what feels "enough." +- All spacing values from the token scale. No magic numbers. +- CSS Grid for 2D layouts, Flexbox for 1D — use `gap`, never margin hacks. +- Mobile-first: design at 320px, enhance upward through breakpoints. +- Touch targets: minimum 44x44px. + +## Backgrounds & Atmosphere + +Create depth — never flat solid colors: +- Gradient meshes, noise textures, geometric patterns +- Layered transparencies, dramatic shadows from the token scale +- Grain overlays, subtle dot/grid patterns +- Blur effects for depth on overlapping elements + +## Motion + +- One orchestrated page load with staggered reveals > scattered micro-interactions. +- Only animate `transform` and `opacity` — no layout-triggering properties. +- Respect `prefers-reduced-motion`. +- Hover/focus transitions: use the `duration-fast` / `duration-normal` tokens. +- Scroll animations: Intersection Observer, not scroll listeners. + +## Accessibility (non-negotiable) + +- Keyboard-accessible interactive elements. +- Meaningful `alt` text on images. Decorative: `alt=""`. +- Form inputs: associated `