name: clean-code
description: The Foundation Skill. LLM Firewall + 2025 Security + Cross-Skill Coordination. Use for ALL code output - prevents hallucinations, enforces security, ensures quality.

🛡️ CLEAN CODE: THE FOUNDATION

Philosophy: This skill is the FOUNDATION - it applies to ALL other skills. Every piece of code must pass these gates.
ALGORITHMIC ELEGANCE MANDATE (CRITICAL): Never prioritize "clever" code over readable, intent-revealing engineering. AI-generated code often fails by introducing unnecessary abstractions or using vague naming conventions that obscure logic. You MUST use intent-revealing names for every variable and function. Any implementation that increases cognitive complexity without a proportional gain in performance or scalability must be rejected. Avoid "Hype-Driven Development"—proven patterns trump trending but unstable frameworks.

🚨 IRON LAWS

1. NO HALLUCINATED PACKAGES - Verify before import
2. NO LAZY PLACEHOLDERS - Code must be runnable
3. NO SECURITY SHORTCUTS - Production-ready defaults
4. NO OVER-ENGINEERING - Simplest solution first

📦 PROTOCOL 1: SUPPLY CHAIN SECURITY

LLMs hallucinate packages that sound real but don't exist.
1. Verify before import - npm search or pip show for unfamiliar packages
2. Prefer battle-tested - lodash, date-fns, zod over obscure alternatives
3. Check npm audit / pip-audit before adding new dependencies
4. Pin versions in production - no ^ or ~ for critical deps
2025 AI Package Risks:
- Never import AI "wrapper" libraries without verification
- LLM SDKs: Use official only (openai, anthropic, google-generativeai)
- Vector DBs: Stick to established (pinecone, weaviate, chromadb)

🔐 PROTOCOL 2: SECURITY-FIRST DEFAULTS

Frontend Security:
| Forbidden | Required |
|-----------|----------|
| dangerouslySetInnerHTML | DOMPurify sanitization |
| Inline event handlers | Event delegation |
| eval(), new Function() | Static code only |
| Storing tokens in localStorage | httpOnly cookies |
Backend Security:
| Forbidden | Required |
|-----------|----------|
| CORS: * | Explicit origin whitelist |
| Raw SQL strings | Parameterized queries |
| chmod 777 | Principle of least privilege |
| Hardcoded secrets | Environment variables + validation |
API Security (2025):
- Rate limiting on ALL public endpoints
- Input validation at the gate (Zod/Pydantic)
- Output sanitization for AI-generated content
- PASETO > JWT for new projects

🏗️ PROTOCOL 3: NO LAZY PLACEHOLDERS

Forbidden Patterns:

// ❌ BANNED
// TODO: Implement this
// ... logic goes here
function placeholder() { }
throw new Error('Not implemented');

Required:
- Every function must be runnable
- If too complex, break into smaller complete functions
- "Hurry" is not an excuse - write minimal viable implementation

📐 PROTOCOL 4: MODULARITY & STRUCTURE

The 50/300 Rule:
- Functions > 50 lines → Break down
- Files > 300 lines → Split into modules
SOLID Principles:
| Principle | Quick Check |
|-----------|-------------|
| Single Responsibility | Does this do ONE thing? |
| Open/Closed | Can I extend without modifying? |
| Liskov Substitution | Can subtypes replace parent? |
| Interface Segregation | Are interfaces minimal? |
| Dependency Inversion | Do I depend on abstractions? |

🎯 PROTOCOL 5: COMPLEXITY CAP

Native First:

// ❌ Don't install is-odd
npm install is-odd
// ✅ Use native
const isOdd = n => n % 2 !== 0;

Anti-Patterns:
- AbstractFactoryBuilderManager for simple functions
- 10 layers of abstraction for CRUD
- "Future-proofing" for requirements that don't exist
YAGNI: You Aren't Gonna Need It. Build for today's requirements.

🔄 PROTOCOL 6: DEPENDENCY HYGIENE

Freshness Check:

npm outdated      # Check for updates
npm audit         # Check for vulnerabilities

The CVE Brake:
- "Latest" is not always "Safest"
- If latest has Critical CVE → Rollback to last secure version
- Security > New Features
2025 Recommended:
| Category | Recommended |
|----------|-------------|
| Validation | zod, valibot |
| HTTP | ky, ofetch |
| State | zustand, jotai |
| ORM | drizzle, prisma |
| Auth | lucia, better-auth |

🤖 PROTOCOL 7: AI-ERA CONSIDERATIONS

When Building AI Features:
1. Validate AI outputs - Never trust raw LLM responses
2. Rate limit AI calls - Prevent cost explosions
3. Sanitize before display - AI can generate malicious content
4. Log AI interactions - For debugging and compliance
When AI is Writing Code:
1. Verify imports exist - AI hallucinates packages
2. Check types are correct - AI guesses at APIs
3. Test edge cases - AI misses boundary conditions
4. Review security - AI takes shortcuts

✅ QUICK AUDIT CHECKLIST

Before committing ANY code:
- [ ] No hallucinated imports (verified packages exist)
- [ ] No security shortcuts (CORS, eval, hardcoded secrets)
- [ ] No lazy placeholders (// TODO, empty functions)
- [ ] Functions < 50 lines, files < 300 lines
- [ ] Dependencies audited (npm audit clean)
- [ ] Types are strict (no any)

🔗 CROSS-SKILL INTEGRATION