docs: improve README with agent guide, FAQ, and fix component counts

- Fix inaccurate counts: 13 agents (was 15+), 34 skills (was 30+), 31 commands (was 30) - Add "Which Agent Should I Use?" decision table with common workflows - Add FAQ section addressing top recurring issues (hooks, context window, cross-platform) - Add 5 missing skills and 7 missing commands to directory tree listing - Expand code-reviewer agent with React/Next.js, Node.js patterns, and confidence filtering - Add real-world SaaS example (Next.js + Supabase + Stripe) in examples/
2026-03-30 13:43:26 +08:00 · 2026-02-12 13:24:24 -08:00
parent 501bf23ca0
commit b57eef4f71
3 changed files with 492 additions and 78 deletions
--- 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
@@ -306,6 +318,7 @@ everything-claude-code/
 |-- examples/         # Example configurations and sessions
 |   |-- 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 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** |
--- 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
+<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:
-```
-[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.
--- a/examples/saas-nextjs-CLAUDE.md
+++ 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`