The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: improve README with agent guide, FAQ, and fix component counts
Affaan Mustafab57eef4f7153
diff --git a/README.md b/README.mdindex 8c10fd4bf..ef78ea3c4 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++<details>+<summary><b>How do I check which agents/commands are installed?</b></summary>++```bash+/plugin list everything-claude-code@everything-claude-code+```++This shows all available agents, commands, and skills from the plugin.+</details>++<details>+<summary><b>My hooks aren't working / I see "Duplicate hooks file" errors</b></summary>++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).+</details>++<details>+<summary><b>My context window is shrinking / Claude is running out of context</b></summary>++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.+</details>++<details>+<summary><b>Can I use only some components (e.g., just agents)?</b></summary>++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.+</details>++<details>+<summary><b>Does this work with Cursor / OpenCode?</b></summary>++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.+</details>++<details>+<summary><b>How do I contribute a new skill or agent?</b></summary>++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+</details>++---+## 🧪 Running TestsThe 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.mdindex 8ed274d91..dec0e0626 100644--- a/agents/code-reviewer.md+++ b/agents/code-reviewer.md@@ -7,98 +7,218 @@ model: sonnetYou 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--Provide feedback organized by priority:-- Critical issues (must fix)-- Warnings (should fix)-- Suggestions (consider improving)--Include specific examples of how to fix issues.--## Security Checks (CRITICAL)--- 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--## Code Quality (HIGH)--- 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--## Performance (MEDIUM)--- 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--## Best Practices (MEDIUM)--- 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++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).++## Confidence-Based Filtering++**IMPORTANT**: Do not flood the review with noise. Apply these filters:++- **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++## Review Checklist++### Security (CRITICAL)++These MUST be flagged — they can cause real damage:++- **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)++```typescript+// BAD: SQL injection via string concatenation+const query = `SELECT * FROM users WHERE id = ${userId}`;++// GOOD: Parameterized query+const query = `SELECT * FROM users WHERE id = $1`;+const result = await db.query(query, [userId]);+```++```typescript+// BAD: Rendering raw user HTML without sanitization+// Always sanitize user content with DOMPurify.sanitize() or equivalent++// GOOD: Use text content or sanitize+<div>{userComment}</div>+```++### 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) => <ListItem key={i} item={item} />)}++// GOOD: Stable unique key+{items.map(item => <ListItem key={item.id} item={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:+Organize findings by severity. For each issue:+```-[CRITICAL] Hardcoded API key+[CRITICAL] Hardcoded API key in sourceFile: src/api/client.ts:42-Issue: API key exposed in source code-Fix: Move to environment variable+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:-const apiKey = "sk-abc123"; // ❌ Bad-const apiKey = process.env.API_KEY; // ✓ Good+```+## 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-## Project-Specific Guidelines (Example)+When available, also check project-specific conventions from `CLAUDE.md` or project rules:-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+- 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)-Customize based on your project's `CLAUDE.md` or skill files.+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.mdnew file mode 100644index 000000000..115983198--- /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<T> =+ | { 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`