diff --git a/README.md b/README.md index 8c10fd4b..ef78ea3c 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ For manual install instructions see the README in the `rules/` folder. /plugin list everything-claude-code@everything-claude-code ``` -✨ **That's it!** You now have access to 15+ agents, 30+ skills, and 30+ commands. +✨ **That's it!** You now have access to 13 agents, 34 skills, and 31 commands. --- @@ -234,6 +234,11 @@ everything-claude-code/ | |-- springboot-verification/ # Spring Boot verification (NEW) | |-- configure-ecc/ # Interactive installation wizard (NEW) | |-- security-scan/ # AgentShield security auditor integration (NEW) +| |-- java-coding-standards/ # Java coding standards (NEW) +| |-- jpa-patterns/ # JPA/Hibernate patterns (NEW) +| |-- postgres-patterns/ # PostgreSQL optimization patterns (NEW) +| |-- nutrient-document-processing/ # Document processing with Nutrient API (NEW) +| |-- project-guidelines-example/ # Template for project-specific skills | |-- commands/ # Slash commands for quick execution | |-- tdd.md # /tdd - Test-driven development @@ -260,6 +265,13 @@ everything-claude-code/ | |-- multi-backend.md # /multi-backend - Backend multi-service orchestration (NEW) | |-- multi-frontend.md # /multi-frontend - Frontend multi-service orchestration (NEW) | |-- multi-workflow.md # /multi-workflow - General multi-service workflows (NEW) +| |-- orchestrate.md # /orchestrate - Multi-agent coordination +| |-- sessions.md # /sessions - Session history management +| |-- eval.md # /eval - Evaluate against criteria +| |-- test-coverage.md # /test-coverage - Test coverage analysis +| |-- update-docs.md # /update-docs - Update documentation +| |-- update-codemaps.md # /update-codemaps - Update codemaps +| |-- python-review.md # /python-review - Python code review (NEW) | |-- rules/ # Always-follow guidelines (copy to ~/.claude/rules/) | |-- README.md # Structure overview and installation guide @@ -304,8 +316,9 @@ everything-claude-code/ | |-- research.md # Research/exploration mode context | |-- examples/ # Example configurations and sessions -| |-- CLAUDE.md # Example project-level config -| |-- user-CLAUDE.md # Example user-level config +| |-- CLAUDE.md # Example project-level config +| |-- user-CLAUDE.md # Example user-level config +| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe) | |-- mcp-configs/ # MCP server configurations | |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc. @@ -567,6 +580,121 @@ See [`rules/README.md`](rules/README.md) for installation and structure details. --- +## πŸ—ΊοΈ Which Agent Should I Use? + +Not sure where to start? Use this quick reference: + +| I want to... | Use this command | Agent used | +|--------------|-----------------|------------| +| Plan a new feature | `/plan "Add auth"` | planner | +| Design system architecture | `/plan` + architect agent | architect | +| Write code with tests first | `/tdd` | tdd-guide | +| Review code I just wrote | `/code-review` | code-reviewer | +| Fix a failing build | `/build-fix` | build-error-resolver | +| Run end-to-end tests | `/e2e` | e2e-runner | +| Find security vulnerabilities | `/security-scan` | security-reviewer | +| Remove dead code | `/refactor-clean` | refactor-cleaner | +| Update documentation | `/update-docs` | doc-updater | +| Review Go code | `/go-review` | go-reviewer | +| Review Python code | `/python-review` | python-reviewer | +| Audit database queries | *(auto-delegated)* | database-reviewer | + +### Common Workflows + +**Starting a new feature:** +``` +/plan "Add user authentication with OAuth" β†’ planner creates implementation blueprint +/tdd β†’ tdd-guide enforces write-tests-first +/code-review β†’ code-reviewer checks your work +``` + +**Fixing a bug:** +``` +/tdd β†’ tdd-guide: write a failing test that reproduces it + β†’ implement the fix, verify test passes +/code-review β†’ code-reviewer: catch regressions +``` + +**Preparing for production:** +``` +/security-scan β†’ security-reviewer: OWASP Top 10 audit +/e2e β†’ e2e-runner: critical user flow tests +/test-coverage β†’ verify 80%+ coverage +``` + +--- + +## ❓ FAQ + +
+How do I check which agents/commands are installed? + +```bash +/plugin list everything-claude-code@everything-claude-code +``` + +This shows all available agents, commands, and skills from the plugin. +
+ +
+My hooks aren't working / I see "Duplicate hooks file" errors + +This is the most common issue. **Do NOT add a `"hooks"` field to `.claude-plugin/plugin.json`.** Claude Code v2.1+ automatically loads `hooks/hooks.json` from installed plugins. Explicitly declaring it causes duplicate detection errors. See [#29](https://github.com/affaan-m/everything-claude-code/issues/29), [#52](https://github.com/affaan-m/everything-claude-code/issues/52), [#103](https://github.com/affaan-m/everything-claude-code/issues/103). +
+ +
+My context window is shrinking / Claude is running out of context + +Too many MCP servers eat your context. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k. + +**Fix:** Disable unused MCPs per project: +```json +// In your project's .claude/settings.json +{ + "disabledMcpServers": ["supabase", "railway", "vercel"] +} +``` + +Keep under 10 MCPs enabled and under 80 tools active. +
+ +
+Can I use only some components (e.g., just agents)? + +Yes. Use Option 2 (manual installation) and copy only what you need: + +```bash +# Just agents +cp everything-claude-code/agents/*.md ~/.claude/agents/ + +# Just rules +cp -r everything-claude-code/rules/common/* ~/.claude/rules/ +``` + +Each component is fully independent. +
+ +
+Does this work with Cursor / OpenCode? + +Yes. ECC is cross-platform: +- **Cursor**: Pre-translated configs in `.cursor/`. See [Cursor IDE Support](#cursor-ide-support). +- **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#-opencode-support). +- **Claude Code**: Native β€” this is the primary target. +
+ +
+How do I contribute a new skill or agent? + +See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: +1. Fork the repo +2. Create your skill in `skills/your-skill-name/SKILL.md` (with YAML frontmatter) +3. Or create an agent in `agents/your-agent.md` +4. Submit a PR with a clear description of what it does and when to use it +
+ +--- + ## πŸ§ͺ Running Tests The plugin includes a comprehensive test suite: @@ -655,9 +783,9 @@ The configuration is automatically detected from `.opencode/opencode.json`. | Feature | Claude Code | OpenCode | Status | |---------|-------------|----------|--------| -| Agents | βœ… 14 agents | βœ… 12 agents | **Claude Code leads** | -| Commands | βœ… 30 commands | βœ… 24 commands | **Claude Code leads** | -| Skills | βœ… 28 skills | βœ… 16 skills | **Claude Code leads** | +| Agents | βœ… 13 agents | βœ… 12 agents | **Claude Code leads** | +| Commands | βœ… 31 commands | βœ… 24 commands | **Claude Code leads** | +| Skills | βœ… 34 skills | βœ… 16 skills | **Claude Code leads** | | Hooks | βœ… 3 phases | βœ… 20+ events | **OpenCode has more!** | | Rules | βœ… 8 rules | βœ… 8 rules | **Full parity** | | MCP Servers | βœ… Full | βœ… Full | **Full parity** | diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index 8ed274d9..dec0e062 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -7,98 +7,218 @@ model: sonnet You are a senior code reviewer ensuring high standards of code quality and security. +## Review Process + When invoked: -1. Run git diff to see recent changes -2. Focus on modified files -3. Begin review immediately -Review checklist: -- Code is simple and readable -- Functions and variables are well-named -- No duplicated code -- Proper error handling -- No exposed secrets or API keys -- Input validation implemented -- Good test coverage -- Performance considerations addressed -- Time complexity of algorithms analyzed -- Licenses of integrated libraries checked +1. **Gather context** β€” Run `git diff --staged` and `git diff` to see all changes. If no diff, check recent commits with `git log --oneline -5`. +2. **Understand scope** β€” Identify which files changed, what feature/fix they relate to, and how they connect. +3. **Read surrounding code** β€” Don't review changes in isolation. Read the full file and understand imports, dependencies, and call sites. +4. **Apply review checklist** β€” Work through each category below, from CRITICAL to LOW. +5. **Report findings** β€” Use the output format below. Only report issues you are confident about (>80% sure it is a real problem). -Provide feedback organized by priority: -- Critical issues (must fix) -- Warnings (should fix) -- Suggestions (consider improving) +## Confidence-Based Filtering -Include specific examples of how to fix issues. +**IMPORTANT**: Do not flood the review with noise. Apply these filters: -## Security Checks (CRITICAL) +- **Report** if you are >80% confident it is a real issue +- **Skip** stylistic preferences unless they violate project conventions +- **Skip** issues in unchanged code unless they are CRITICAL security issues +- **Consolidate** similar issues (e.g., "5 functions missing error handling" not 5 separate findings) +- **Prioritize** issues that could cause bugs, security vulnerabilities, or data loss -- Hardcoded credentials (API keys, passwords, tokens) -- SQL injection risks (string concatenation in queries) -- XSS vulnerabilities (unescaped user input) -- Missing input validation -- Insecure dependencies (outdated, vulnerable) -- Path traversal risks (user-controlled file paths) -- CSRF vulnerabilities -- Authentication bypasses +## Review Checklist -## Code Quality (HIGH) +### Security (CRITICAL) -- Large functions (>50 lines) -- Large files (>800 lines) -- Deep nesting (>4 levels) -- Missing error handling (try/catch) -- console.log statements -- Mutation patterns -- Missing tests for new code +These MUST be flagged β€” they can cause real damage: -## Performance (MEDIUM) +- **Hardcoded credentials** β€” API keys, passwords, tokens, connection strings in source +- **SQL injection** β€” String concatenation in queries instead of parameterized queries +- **XSS vulnerabilities** β€” Unescaped user input rendered in HTML/JSX +- **Path traversal** β€” User-controlled file paths without sanitization +- **CSRF vulnerabilities** β€” State-changing endpoints without CSRF protection +- **Authentication bypasses** β€” Missing auth checks on protected routes +- **Insecure dependencies** β€” Known vulnerable packages +- **Exposed secrets in logs** β€” Logging sensitive data (tokens, passwords, PII) -- Inefficient algorithms (O(nΒ²) when O(n log n) possible) -- Unnecessary re-renders in React -- Missing memoization -- Large bundle sizes -- Unoptimized images -- Missing caching -- N+1 queries +```typescript +// BAD: SQL injection via string concatenation +const query = `SELECT * FROM users WHERE id = ${userId}`; -## Best Practices (MEDIUM) +// GOOD: Parameterized query +const query = `SELECT * FROM users WHERE id = $1`; +const result = await db.query(query, [userId]); +``` -- Emoji usage in code/comments -- TODO/FIXME without tickets -- Missing JSDoc for public APIs -- Accessibility issues (missing ARIA labels, poor contrast) -- Poor variable naming (x, tmp, data) -- Magic numbers without explanation -- Inconsistent formatting +```typescript +// BAD: Rendering raw user HTML without sanitization +// Always sanitize user content with DOMPurify.sanitize() or equivalent + +// GOOD: Use text content or sanitize +
{userComment}
+``` + +### Code Quality (HIGH) + +- **Large functions** (>50 lines) β€” Split into smaller, focused functions +- **Large files** (>800 lines) β€” Extract modules by responsibility +- **Deep nesting** (>4 levels) β€” Use early returns, extract helpers +- **Missing error handling** β€” Unhandled promise rejections, empty catch blocks +- **Mutation patterns** β€” Prefer immutable operations (spread, map, filter) +- **console.log statements** β€” Remove debug logging before merge +- **Missing tests** β€” New code paths without test coverage +- **Dead code** β€” Commented-out code, unused imports, unreachable branches + +```typescript +// BAD: Deep nesting + mutation +function processUsers(users) { + if (users) { + for (const user of users) { + if (user.active) { + if (user.email) { + user.verified = true; // mutation! + results.push(user); + } + } + } + } + return results; +} + +// GOOD: Early returns + immutability + flat +function processUsers(users) { + if (!users) return []; + return users + .filter(user => user.active && user.email) + .map(user => ({ ...user, verified: true })); +} +``` + +### React/Next.js Patterns (HIGH) + +When reviewing React/Next.js code, also check: + +- **Missing dependency arrays** β€” `useEffect`/`useMemo`/`useCallback` with incomplete deps +- **State updates in render** β€” Calling setState during render causes infinite loops +- **Missing keys in lists** β€” Using array index as key when items can reorder +- **Prop drilling** β€” Props passed through 3+ levels (use context or composition) +- **Unnecessary re-renders** β€” Missing memoization for expensive computations +- **Client/server boundary** β€” Using `useState`/`useEffect` in Server Components +- **Missing loading/error states** β€” Data fetching without fallback UI +- **Stale closures** β€” Event handlers capturing stale state values + +```tsx +// BAD: Missing dependency, stale closure +useEffect(() => { + fetchData(userId); +}, []); // userId missing from deps + +// GOOD: Complete dependencies +useEffect(() => { + fetchData(userId); +}, [userId]); +``` + +```tsx +// BAD: Using index as key with reorderable list +{items.map((item, i) => )} + +// GOOD: Stable unique key +{items.map(item => )} +``` + +### Node.js/Backend Patterns (HIGH) + +When reviewing backend code: + +- **Unvalidated input** β€” Request body/params used without schema validation +- **Missing rate limiting** β€” Public endpoints without throttling +- **Unbounded queries** β€” `SELECT *` or queries without LIMIT on user-facing endpoints +- **N+1 queries** β€” Fetching related data in a loop instead of a join/batch +- **Missing timeouts** β€” External HTTP calls without timeout configuration +- **Error message leakage** β€” Sending internal error details to clients +- **Missing CORS configuration** β€” APIs accessible from unintended origins + +```typescript +// BAD: N+1 query pattern +const users = await db.query('SELECT * FROM users'); +for (const user of users) { + user.posts = await db.query('SELECT * FROM posts WHERE user_id = $1', [user.id]); +} + +// GOOD: Single query with JOIN or batch +const usersWithPosts = await db.query(` + SELECT u.*, json_agg(p.*) as posts + FROM users u + LEFT JOIN posts p ON p.user_id = u.id + GROUP BY u.id +`); +``` + +### Performance (MEDIUM) + +- **Inefficient algorithms** β€” O(n^2) when O(n log n) or O(n) is possible +- **Unnecessary re-renders** β€” Missing React.memo, useMemo, useCallback +- **Large bundle sizes** β€” Importing entire libraries when tree-shakeable alternatives exist +- **Missing caching** β€” Repeated expensive computations without memoization +- **Unoptimized images** β€” Large images without compression or lazy loading +- **Synchronous I/O** β€” Blocking operations in async contexts + +### Best Practices (LOW) + +- **TODO/FIXME without tickets** β€” TODOs should reference issue numbers +- **Missing JSDoc for public APIs** β€” Exported functions without documentation +- **Poor naming** β€” Single-letter variables (x, tmp, data) in non-trivial contexts +- **Magic numbers** β€” Unexplained numeric constants +- **Inconsistent formatting** β€” Mixed semicolons, quote styles, indentation ## Review Output Format -For each issue: -``` -[CRITICAL] Hardcoded API key -File: src/api/client.ts:42 -Issue: API key exposed in source code -Fix: Move to environment variable +Organize findings by severity. For each issue: -const apiKey = "sk-abc123"; // ❌ Bad -const apiKey = process.env.API_KEY; // βœ“ Good +``` +[CRITICAL] Hardcoded API key in source +File: src/api/client.ts:42 +Issue: API key "sk-abc..." exposed in source code. This will be committed to git history. +Fix: Move to environment variable and add to .gitignore/.env.example + + const apiKey = "sk-abc123"; // BAD + const apiKey = process.env.API_KEY; // GOOD +``` + +### Summary Format + +End every review with: + +``` +## Review Summary + +| Severity | Count | Status | +|----------|-------|--------| +| CRITICAL | 0 | pass | +| HIGH | 2 | warn | +| MEDIUM | 3 | info | +| LOW | 1 | note | + +Verdict: WARNING β€” 2 HIGH issues should be resolved before merge. ``` ## Approval Criteria -- βœ… Approve: No CRITICAL or HIGH issues -- ⚠️ Warning: MEDIUM issues only (can merge with caution) -- ❌ Block: CRITICAL or HIGH issues found +- **Approve**: No CRITICAL or HIGH issues +- **Warning**: HIGH issues only (can merge with caution) +- **Block**: CRITICAL issues found β€” must fix before merge -## Project-Specific Guidelines (Example) +## Project-Specific Guidelines -Add your project-specific checks here. Examples: -- Follow MANY SMALL FILES principle (200-400 lines typical) -- No emojis in codebase -- Use immutability patterns (spread operator) -- Verify database RLS policies -- Check AI integration error handling -- Validate cache fallback behavior +When available, also check project-specific conventions from `CLAUDE.md` or project rules: -Customize based on your project's `CLAUDE.md` or skill files. +- File size limits (e.g., 200-400 lines typical, 800 max) +- Emoji policy (many projects prohibit emojis in code) +- Immutability requirements (spread operator over mutation) +- Database policies (RLS, migration patterns) +- Error handling patterns (custom error classes, error boundaries) +- State management conventions (Zustand, Redux, Context) + +Adapt your review to the project's established patterns. When in doubt, match what the rest of the codebase does. diff --git a/examples/saas-nextjs-CLAUDE.md b/examples/saas-nextjs-CLAUDE.md new file mode 100644 index 00000000..11598319 --- /dev/null +++ b/examples/saas-nextjs-CLAUDE.md @@ -0,0 +1,166 @@ +# SaaS Application β€” Project CLAUDE.md + +> Real-world example for a Next.js + Supabase + Stripe SaaS application. +> Copy this to your project root and customize for your stack. + +## Project Overview + +**Stack:** Next.js 15 (App Router), TypeScript, Supabase (auth + DB), Stripe (billing), Tailwind CSS, Playwright (E2E) + +**Architecture:** Server Components by default. Client Components only for interactivity. API routes for webhooks and server actions for mutations. + +## Critical Rules + +### Database + +- All queries use Supabase client with RLS enabled β€” never bypass RLS +- Migrations in `supabase/migrations/` β€” never modify the database directly +- Use `select()` with explicit column lists, not `select('*')` +- All user-facing queries must include `.limit()` to prevent unbounded results + +### Authentication + +- Use `createServerClient()` from `@supabase/ssr` in Server Components +- Use `createBrowserClient()` from `@supabase/ssr` in Client Components +- Protected routes check `getUser()` β€” never trust `getSession()` alone for auth +- Middleware in `middleware.ts` refreshes auth tokens on every request + +### Billing + +- Stripe webhook handler in `app/api/webhooks/stripe/route.ts` +- Never trust client-side price data β€” always fetch from Stripe server-side +- Subscription status checked via `subscription_status` column, synced by webhook +- Free tier users: 3 projects, 100 API calls/day + +### Code Style + +- No emojis in code or comments +- Immutable patterns only β€” spread operator, never mutate +- Server Components: no `'use client'` directive, no `useState`/`useEffect` +- Client Components: `'use client'` at top, minimal β€” extract logic to hooks +- Prefer Zod schemas for all input validation (API routes, forms, env vars) + +## File Structure + +``` +src/ + app/ + (auth)/ # Auth pages (login, signup, forgot-password) + (dashboard)/ # Protected dashboard pages + api/ + webhooks/ # Stripe, Supabase webhooks + layout.tsx # Root layout with providers + components/ + ui/ # Shadcn/ui components + forms/ # Form components with validation + dashboard/ # Dashboard-specific components + hooks/ # Custom React hooks + lib/ + supabase/ # Supabase client factories + stripe/ # Stripe client and helpers + utils.ts # General utilities + types/ # Shared TypeScript types +supabase/ + migrations/ # Database migrations + seed.sql # Development seed data +``` + +## Key Patterns + +### API Response Format + +```typescript +type ApiResponse = + | { success: true; data: T } + | { success: false; error: string; code?: string } +``` + +### Server Action Pattern + +```typescript +'use server' + +import { z } from 'zod' +import { createServerClient } from '@/lib/supabase/server' + +const schema = z.object({ + name: z.string().min(1).max(100), +}) + +export async function createProject(formData: FormData) { + const parsed = schema.safeParse({ name: formData.get('name') }) + if (!parsed.success) { + return { success: false, error: parsed.error.flatten() } + } + + const supabase = await createServerClient() + const { data: { user } } = await supabase.auth.getUser() + if (!user) return { success: false, error: 'Unauthorized' } + + const { data, error } = await supabase + .from('projects') + .insert({ name: parsed.data.name, user_id: user.id }) + .select('id, name, created_at') + .single() + + if (error) return { success: false, error: 'Failed to create project' } + return { success: true, data } +} +``` + +## Environment Variables + +```bash +# Supabase +NEXT_PUBLIC_SUPABASE_URL= +NEXT_PUBLIC_SUPABASE_ANON_KEY= +SUPABASE_SERVICE_ROLE_KEY= # Server-only, never expose to client + +# Stripe +STRIPE_SECRET_KEY= +STRIPE_WEBHOOK_SECRET= +NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY= + +# App +NEXT_PUBLIC_APP_URL=http://localhost:3000 +``` + +## Testing Strategy + +```bash +/tdd # Unit + integration tests for new features +/e2e # Playwright tests for auth flow, billing, dashboard +/test-coverage # Verify 80%+ coverage +``` + +### Critical E2E Flows + +1. Sign up β†’ email verification β†’ first project creation +2. Login β†’ dashboard β†’ CRUD operations +3. Upgrade plan β†’ Stripe checkout β†’ subscription active +4. Webhook: subscription canceled β†’ downgrade to free tier + +## ECC Workflow + +```bash +# Planning a feature +/plan "Add team invitations with email notifications" + +# Developing with TDD +/tdd + +# Before committing +/code-review +/security-scan + +# Before release +/e2e +/test-coverage +``` + +## Git Workflow + +- `feat:` new features, `fix:` bug fixes, `refactor:` code changes +- Feature branches from `main`, PRs required +- CI runs: lint, type-check, unit tests, E2E tests +- Deploy: Vercel preview on PR, production on merge to `main`