zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-03-30 13:43:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
- 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/
This commit is contained in:
Affaan Mustafa
2026-02-12 13:24:24 -08:00
parent 501bf23ca0
commit b57eef4f71
3 changed files with 492 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
README.md
View File

@@ -143,7 +143,7 @@ For manual install instructions see the README in the `rules/` folder.
/plugin list everything-claude-code@everything-claude-code /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) | |-- springboot-verification/ # Spring Boot verification (NEW)
| |-- configure-ecc/ # Interactive installation wizard (NEW) | |-- configure-ecc/ # Interactive installation wizard (NEW)
| |-- security-scan/ # AgentShield security auditor integration (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 |-- commands/ # Slash commands for quick execution
| |-- tdd.md # /tdd - Test-driven development | |-- tdd.md # /tdd - Test-driven development
@@ -260,6 +265,13 @@ everything-claude-code/
| |-- multi-backend.md # /multi-backend - Backend multi-service orchestration (NEW) | |-- multi-backend.md # /multi-backend - Backend multi-service orchestration (NEW)
| |-- multi-frontend.md # /multi-frontend - Frontend multi-service orchestration (NEW) | |-- multi-frontend.md # /multi-frontend - Frontend multi-service orchestration (NEW)
| |-- multi-workflow.md # /multi-workflow - General multi-service workflows (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/) |-- rules/ # Always-follow guidelines (copy to ~/.claude/rules/)
| |-- README.md # Structure overview and installation guide | |-- README.md # Structure overview and installation guide
@@ -304,8 +316,9 @@ everything-claude-code/
| |-- research.md # Research/exploration mode context | |-- research.md # Research/exploration mode context
| |
|-- examples/ # Example configurations and sessions |-- examples/ # Example configurations and sessions
| |-- CLAUDE.md # Example project-level config | |-- CLAUDE.md # Example project-level config
| |-- user-CLAUDE.md # Example user-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-configs/ # MCP server configurations
| |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc. | |-- 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 ## 🧪 Running Tests
The plugin includes a comprehensive test suite: 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 | | Feature | Claude Code | OpenCode | Status |
|---------|-------------|----------|--------| |---------|-------------|----------|--------|
| Agents | ✅ 14 agents | ✅ 12 agents | **Claude Code leads** | | Agents | ✅ 13 agents | ✅ 12 agents | **Claude Code leads** |
| Commands | ✅ 30 commands | ✅ 24 commands | **Claude Code leads** | | Commands | ✅ 31 commands | ✅ 24 commands | **Claude Code leads** |
| Skills | ✅ 28 skills | ✅ 16 skills | **Claude Code leads** | | Skills | ✅ 34 skills | ✅ 16 skills | **Claude Code leads** |
| Hooks | ✅ 3 phases | ✅ 20+ events | **OpenCode has more!** | | Hooks | ✅ 3 phases | ✅ 20+ events | **OpenCode has more!** |
| Rules | ✅ 8 rules | ✅ 8 rules | **Full parity** | | Rules | ✅ 8 rules | ✅ 8 rules | **Full parity** |
| MCP Servers | ✅ Full | ✅ Full | **Full parity** | | MCP Servers | ✅ Full | ✅ Full | **Full parity** |

264
agents/code-reviewer.md
View File

@@ -7,98 +7,218 @@ model: sonnet
You are a senior code reviewer ensuring high standards of code quality and security. You are a senior code reviewer ensuring high standards of code quality and security.
## Review Process
When invoked: When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist: 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`.
- Code is simple and readable 2. **Understand scope** — Identify which files changed, what feature/fix they relate to, and how they connect.
- Functions and variables are well-named 3. **Read surrounding code** — Don't review changes in isolation. Read the full file and understand imports, dependencies, and call sites.
- No duplicated code 4. **Apply review checklist** — Work through each category below, from CRITICAL to LOW.
- Proper error handling 5. **Report findings** — Use the output format below. Only report issues you are confident about (>80% sure it is a real problem).
- 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: ## Confidence-Based Filtering
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
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) ## Review Checklist
- 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) ### Security (CRITICAL)
- Large functions (>50 lines) These MUST be flagged — they can cause real damage:
- 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) - **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) ```typescript
- Unnecessary re-renders in React // BAD: SQL injection via string concatenation
- Missing memoization const query = `SELECT * FROM users WHERE id = ${userId}`;
- Large bundle sizes
- Unoptimized images
- Missing caching
- N+1 queries
## 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 ```typescript
- TODO/FIXME without tickets // BAD: Rendering raw user HTML without sanitization
- Missing JSDoc for public APIs // Always sanitize user content with DOMPurify.sanitize() or equivalent
- Accessibility issues (missing ARIA labels, poor contrast)
- Poor variable naming (x, tmp, data) // GOOD: Use text content or sanitize
- Magic numbers without explanation <div>{userComment}</div>
- Inconsistent formatting ```
### 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 ## Review Output Format
For each issue: Organize findings by severity. 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
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 ## Approval Criteria
- ✅ Approve: No CRITICAL or HIGH issues - **Approve**: No CRITICAL or HIGH issues
- ⚠️ Warning: MEDIUM issues only (can merge with caution) - **Warning**: HIGH issues only (can merge with caution)
- ❌ Block: CRITICAL or HIGH issues found - **Block**: CRITICAL issues found — must fix before merge
## Project-Specific Guidelines (Example) ## Project-Specific Guidelines
Add your project-specific checks here. Examples: When available, also check project-specific conventions from `CLAUDE.md` or project rules:
- 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
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.

166
examples/saas-nextjs-CLAUDE.md Normal file
View File

@@ -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`