cortexhawk 3.1.0

package/skills/meta/mcp-builder/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: mcp-builder
+description: Guide for building MCP (Model Context Protocol) servers — tools, resources, prompts, transport setup.
+---
+
+# MCP Builder
+
+## MCP Server Structure
+```
+my-mcp-server/
+├── package.json
+├── src/
+│   └── index.ts       # Server entry point
+└── README.md
+```
+
+## Minimal TypeScript Server
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+
+server.tool("my_tool", "Description of what this tool does", {
+  param1: z.string().describe("Parameter description"),
+}, async ({ param1 }) => ({
+  content: [{ type: "text", text: `Result: ${param1}` }]
+}));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Python Server (FastMCP)
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+@mcp.tool()
+def my_tool(param1: str) -> str:
+    """Description of what this tool does."""
+    return f"Result: {param1}"
+
+mcp.run(transport="stdio")
+```
+
+## Rules
+- Use stdio transport for local, HTTP/SSE for remote
+- Every tool needs a clear description (Claude uses it for selection)
+- Input validation with schemas (Zod for TS, Pydantic for Python)
+- Return structured errors, not exceptions
+- Keep tools focused — one action per tool

package/skills/meta/skill-creator/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: skill-creator
+description: Guide for creating new CortexHawk skills with proper structure and frontmatter.
+---
+
+# Skill Creator
+
+## Structure
+```
+skills/[category]/[skill-name]/
+├── SKILL.md          # Required — instructions and metadata
+├── scripts/          # Optional — helper scripts
+│   └── helper.py
+└── resources/        # Optional — templates, configs
+    └── template.json
+```
+
+## SKILL.md Template
+```markdown
+---
+name: [skill-name]
+description: [When to use this skill — 1 sentence, be specific]
+detect: [base | <file> | <file>:<pattern> | dir:<path> — omit if not auto-detectable]
+---
+
+# [Skill Name]
+
+## [Core Content]
+[Instructions Claude follows when this skill is active]
+
+## [Examples]
+[Concrete examples with code]
+
+## [Checklist / Rules]
+[Actionable items]
+```
+
+## Guidelines
+- Description must be specific enough for auto-discovery to work
+- Keep total content under 4K tokens — Claude loads it into context
+- Use code examples over prose explanations
+- Checklists are better than paragraphs
+- Test the skill: ask Claude something matching the description and verify it loads

package/skills/optimization/performance/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: performance
+description: Profiling, N+1 detection, caching strategies, lazy loading, and bundle analysis.
+---
+
+# Performance Optimization
+
+## Profiling Checklist
+- [ ] Identify the bottleneck BEFORE optimizing — measure, don't guess
+- [ ] Profile in production-like conditions (data size, concurrency)
+- [ ] Set a target metric (response time, memory, bundle size)
+- [ ] Measure after each change — verify improvement
+
+## N+1 Query Detection
+```sql
+-- BAD: N+1 — 1 query for users + N queries for posts
+SELECT * FROM users;
+SELECT * FROM posts WHERE user_id = 1;
+SELECT * FROM posts WHERE user_id = 2;
+-- ... N more queries
+
+-- GOOD: Eager load with JOIN or IN
+SELECT u.*, p.* FROM users u LEFT JOIN posts p ON u.id = p.user_id;
+-- Or
+SELECT * FROM posts WHERE user_id IN (1, 2, 3, ...);
+```
+
+## Caching Strategies
+| Strategy | Use When | TTL |
+|---|---|---|
+| In-memory (Map/LRU) | Hot data, single instance | Seconds-minutes |
+| Redis/Memcached | Shared cache, multi-instance | Minutes-hours |
+| HTTP Cache-Control | Static assets, API responses | Hours-days |
+| CDN | Static files, images, fonts | Days-weeks |
+| Memoization | Pure function results | Request lifetime |
+
+```typescript
+// Simple LRU cache
+const cache = new Map();
+function cached<T>(key: string, ttl: number, fn: () => T): T {
+  const entry = cache.get(key);
+  if (entry && Date.now() - entry.time < ttl) return entry.value;
+  const value = fn();
+  cache.set(key, { value, time: Date.now() });
+  return value;
+}
+```
+
+## Frontend
+- Lazy load routes and heavy components: `React.lazy()`, dynamic `import()`
+- Images: `loading="lazy"`, `srcset` for responsive, WebP/AVIF formats
+- Bundle analysis: `webpack-bundle-analyzer`, `vite-plugin-inspect`
+- Tree shaking: named imports, avoid barrel files re-exporting everything
+- Debounce search inputs, throttle scroll/resize handlers
+
+## Backend
+- Connection pooling for databases (don't create per-request connections)
+- Pagination on all list endpoints — never return unbounded results
+- Async I/O for network/disk operations
+- Stream large responses instead of buffering in memory
+- Index columns used in WHERE, ORDER BY, JOIN conditions
+
+## Checklist
+- Measure before optimizing — no premature optimization
+- One change at a time — isolate impact
+- N+1 queries are the #1 backend performance killer — always check
+- Cache invalidation strategy is as important as the cache itself
+- Bundle size: aim for <200KB initial JS (gzipped)
+- Time to Interactive: aim for <3s on 3G
+- Database: EXPLAIN ANALYZE on slow queries

package/skills/quality/complexity-analyzer/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: complexity-analyzer
+description: Analyze code complexity — cyclomatic complexity, cognitive complexity, dependency depth.
+---
+
+# Complexity Analyzer
+
+## Metrics
+- **Cyclomatic complexity** — Number of independent paths. Target: ≤10 per function
+- **Cognitive complexity** — How hard to understand. Target: ≤15 per function
+- **Dependency depth** — Import chain length. Target: ≤4 levels
+- **Function length** — Lines of code. Target: ≤30 lines
+- **Parameter count** — Function arguments. Target: ≤4 params
+
+## Complexity Reducers
+- Extract method (split complex function)
+- Replace conditional with polymorphism
+- Early returns (reduce nesting)
+- Lookup tables (replace switch/if chains)
+- Decompose boolean expressions into named variables
+
+## Examples
+```python
+# Cyclomatic complexity: 6 (too high)
+def check(user, action, resource):
+    if user.is_admin:
+        return True
+    if action == "read" and resource.is_public:
+        return True
+    if action == "write" and user.id == resource.owner_id:
+        return True
+    if action == "delete" and user.role == "moderator":
+        return True
+    return False
+
+# Reduced to 1 with lookup table
+RULES = {
+    lambda u, r: u.is_admin: {"read", "write", "delete"},
+    lambda u, r: r.is_public: {"read"},
+    lambda u, r: u.id == r.owner_id: {"read", "write"},
+    lambda u, r: u.role == "moderator": {"read", "delete"},
+}
+
+def check(user, action, resource):
+    return any(action in actions for pred, actions in RULES.items() if pred(user, resource))
+```
+
+## Process
+1. Scan target files for functions exceeding thresholds
+2. Rank by severity (highest complexity first)
+3. Suggest specific refactoring for each
+4. Estimate effort (lines to change, risk level)

package/skills/quality/error-handling/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: error-handling
+description: Error handling patterns — Result types, exceptions, retry with backoff, circuit breaker, and boundary validation.
+detect: base
+---
+
+# Error Handling
+
+## Result Type Pattern (TypeScript)
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; data: T }
+  | { ok: false; error: E };
+
+function parseUser(input: unknown): Result<User, string> {
+  if (!isValidUser(input)) return { ok: false, error: "Invalid user data" };
+  return { ok: true, data: input as User };
+}
+
+// Usage — forces caller to handle both cases
+const result = parseUser(data);
+if (!result.ok) {
+  logger.error(result.error);
+  return res.status(400).json({ error: result.error });
+}
+const user = result.data; // TypeScript knows this is User
+```
+
+## Exception Patterns (Python)
+```python
+# Custom exception hierarchy
+class AppError(Exception):
+    def __init__(self, message: str, code: str, status: int = 500):
+        self.message = message
+        self.code = code
+        self.status = status
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, id: str):
+        super().__init__(f"{resource} {id} not found", "NOT_FOUND", 404)
+
+class ValidationError(AppError):
+    def __init__(self, details: list[dict]):
+        super().__init__("Validation failed", "VALIDATION_ERROR", 400)
+        self.details = details
+
+# Global handler
+@app.exception_handler(AppError)
+async def handle_app_error(request, exc: AppError):
+    return JSONResponse(status_code=exc.status, content={
+        "error": {"code": exc.code, "message": exc.message}
+    })
+```
+
+## Retry with Exponential Backoff
+```python
+import asyncio
+import random
+
+async def retry(fn, max_attempts=3, base_delay=1.0):
+    for attempt in range(max_attempts):
+        try:
+            return await fn()
+        except Exception as e:
+            if attempt == max_attempts - 1:
+                raise
+            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
+            await asyncio.sleep(delay)
+```
+
+```typescript
+async function retry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
+  for (let i = 0; i < maxAttempts; i++) {
+    try { return await fn(); }
+    catch (e) {
+      if (i === maxAttempts - 1) throw e;
+      await new Promise(r => setTimeout(r, 1000 * 2 ** i + Math.random() * 1000));
+    }
+  }
+  throw new Error("unreachable");
+}
+```
+
+## Circuit Breaker
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private lastFailure = 0;
+  private state: "closed" | "open" | "half-open" = "closed";
+
+  constructor(private threshold = 5, private resetMs = 30000) {}
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === "open") {
+      if (Date.now() - this.lastFailure > this.resetMs) {
+        this.state = "half-open";
+      } else {
+        throw new Error("Circuit breaker is open");
+      }
+    }
+    try {
+      const result = await fn();
+      this.failures = 0;
+      this.state = "closed";
+      return result;
+    } catch (e) {
+      this.failures++;
+      this.lastFailure = Date.now();
+      if (this.failures >= this.threshold) this.state = "open";
+      throw e;
+    }
+  }
+}
+```
+
+## Checklist
+- Validate at system boundaries only (user input, external APIs) — trust internal code
+- Never swallow errors silently — log or propagate
+- Custom error types with machine-readable codes, not just messages
+- Retry only idempotent operations (GET, PUT, DELETE) — never blind retry on POST
+- Circuit breaker for external service calls — fail fast when downstream is down
+- Always include correlation ID in error logs for tracing
+- Never expose stack traces or internal details to users

package/skills/quality/log-analyzer/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: log-analyzer
+description: Analyze and improve logging — structured logging, levels, correlation IDs, sensitive data detection.
+---
+
+# Log Analyzer
+
+## Structured Logging
+```python
+# ❌ Unstructured
+logger.info(f"User {user_id} created order {order_id}")
+
+# ✅ Structured
+logger.info("order_created", extra={"user_id": user_id, "order_id": order_id})
+```
+
+## Log Levels
+| Level | Use for |
+|---|---|
+| ERROR | Something failed, needs attention |
+| WARN | Unexpected but handled, potential issue |
+| INFO | Key business events (user created, order placed) |
+| DEBUG | Development details, not in production |
+
+## Checklist
+- [ ] Structured format (JSON in production)
+- [ ] Correlation/request ID on every log entry
+- [ ] No PII in logs (emails, passwords, tokens, IPs)
+- [ ] Error logs include stack trace and context
+- [ ] Log rotation configured
+- [ ] Centralized log aggregation (ELK, Grafana Loki, etc.)

package/skills/quality/pattern-detector/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: pattern-detector
+description: Detect code smells, anti-patterns, and design issues.
+---
+
+# Pattern Detector
+
+## Code Smells
+- **Long function** (>30 lines) → extract functions
+- **Deep nesting** (>3 levels) → early returns, extract
+- **God class** (>300 lines, >10 methods) → split by responsibility
+- **Feature envy** (method uses another class more than its own) → move method
+- **Primitive obsession** (raw strings/ints for structured data) → value objects
+- **Shotgun surgery** (one change = edits in many places) → consolidate
+- **Dead code** (unreachable, unused imports, commented out) → delete it
+
+## Anti-Patterns
+- Callback hell → async/await
+- Magic numbers/strings → named constants
+- Copy-paste code → extract shared function
+- Catch-all exception handling → specific exceptions
+- Boolean parameters → separate functions or enums
+- Mutable global state → dependency injection
+
+## Examples
+```python
+# BAD: deep nesting
+def process(data):
+    if data:
+        if data.valid:
+            if data.items:
+                for item in data.items:
+                    handle(item)
+
+# GOOD: early returns
+def process(data):
+    if not data or not data.valid or not data.items:
+        return
+    for item in data.items:
+        handle(item)
+```
+
+```typescript
+// BAD: magic numbers
+if (password.length < 8) { ... }
+
+// GOOD: named constant
+const MIN_PASSWORD_LENGTH = 8;
+if (password.length < MIN_PASSWORD_LENGTH) { ... }
+```

package/skills/security/auth-analyzer/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: auth-analyzer
+description: Audit authentication and authorization — OAuth2, JWT, sessions, RBAC, password policy, and common auth vulnerabilities.
+detect: package.json:passport package.json:next-auth package.json:bcrypt package.json:jose requirements.txt:authlib requirements.txt:bcrypt requirements.txt:passlib requirements.txt:pyjwt pyproject.toml:authlib pyproject.toml:bcrypt pyproject.toml:passlib pyproject.toml:pyjwt
+---
+
+# Auth Analyzer
+
+## OAuth2 Flows
+| Flow | Use Case | Security |
+|---|---|---|
+| Authorization Code + PKCE | SPAs, mobile | Recommended |
+| Authorization Code | Server-side web | Recommended |
+| Client Credentials | Machine-to-machine | Service only |
+| Device Code | IoT, CLI | Limited UI |
+| ~~Implicit~~ | ~~Legacy~~ | Never use |
+| ~~Resource Owner Password~~ | ~~Legacy~~ | Never use |
+
+### PKCE Flow
+```
+1. Generate code_verifier (CSPRNG, 43-128 chars)
+2. code_challenge = base64url(sha256(code_verifier))
+3. Redirect to /authorize with code_challenge + state
+4. Validate state on callback
+5. Exchange code + code_verifier at /token
+6. Store access_token in memory, refresh_token in httpOnly cookie
+```
+
+## JWT Checklist
+- [ ] Algorithm whitelist only — RS256/ES256 for distributed, never `none`
+- [ ] Short expiration (access: 15min, refresh: 7-30 days)
+- [ ] Refresh token rotation (invalidate old on use)
+- [ ] Store in httpOnly cookie or memory (never localStorage)
+- [ ] Validate `iss`, `aud`, `exp`, `iat` on every request
+- [ ] No sensitive data in payload (base64, not encrypted)
+- [ ] Key rotation via JWKS with `kid` — rotate every 90 days
+
+### Key Rotation
+```
+1. Generate new key pair, assign new kid
+2. Publish both old + new keys in JWKS
+3. Sign new tokens with new key only
+4. Remove old key after max token lifetime
+```
+
+## Session Security
+- [ ] Session ID from CSPRNG (min 128 bits)
+- [ ] Regenerate ID after login
+- [ ] Timeout: idle (15-60min) + absolute (8-24h)
+- [ ] Secure, HttpOnly, SameSite=Strict cookies
+- [ ] Server-side invalidation on logout
+- [ ] Invalidate all sessions on password change
+
+## Password Policy
+- [ ] Argon2id or bcrypt (cost ≥12) — never SHA256/MD5
+- [ ] Min 8 chars, check against breached lists
+- [ ] Rate limit login (5/min per IP+account)
+- [ ] Lockout after N failures with exponential backoff
+
+## Authorization (RBAC)
+- [ ] Default deny — grant explicitly
+- [ ] Check permissions server-side on every request
+- [ ] No IDOR — verify `user.id == resource.owner_id`
+- [ ] Role hierarchy enforced, reviewed quarterly
+- [ ] Log all access control failures
+
+## Examples
+```python
+# BAD: no algorithm validation
+payload = jwt.decode(token, SECRET, algorithms=None)
+
+# GOOD: explicit whitelist
+payload = jwt.decode(token, SECRET, algorithms=["RS256"])
+```
+
+```typescript
+// BAD: IDOR — no ownership check
+const order = await db.orders.findById(req.params.id);
+
+// GOOD: ownership verified
+const order = await db.orders.findOne({
+  id: req.params.id,
+  userId: req.user.id,
+});
+if (!order) return res.status(404).json({ error: 'Not found' });
+```
+
+## Common Vulnerabilities
+| Issue | Check | Fix |
+|---|---|---|
+| JWT none attack | Algorithm validated? | Whitelist algorithms |
+| IDOR | Ownership checked? | Filter by user_id |
+| Privilege escalation | Role checked on mutation? | Middleware on all routes |
+| Session fixation | ID regenerated? | New ID post-login |
+| Credential stuffing | Rate limiting? | Rate limit + CAPTCHA |
+| Token theft via XSS | Stored in memory? | Never localStorage |

package/skills/security/compliance-checker/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: compliance-checker
+description: Check code against security standards — GDPR/RGPD, OWASP ASVS, SOC 2, PCI DSS, and data classification.
+---
+
+# Compliance Checker
+
+## Data Classification
+```
+Tier 1 — Critical:  Passwords, payment info, SSN, health records
+  Encrypt at rest (AES-256-GCM), strict access control, audit logging
+
+Tier 2 — Sensitive:  PII (name, email, phone, address)
+  Encrypt at rest, access control, logging
+
+Tier 3 — Internal:  Preferences, settings, non-sensitive metadata
+  Standard access control
+
+Tier 4 — Public:  Display names, public posts
+  Standard storage
+```
+
+## GDPR / RGPD (EU Data Protection)
+- [ ] Personal data inventory — what PII, where stored, how long
+- [ ] Consent mechanism before collection
+- [ ] Right to deletion (DELETE endpoint or process)
+- [ ] Right to export (data portability, JSON/CSV)
+- [ ] Data minimization — only collect what's necessary
+- [ ] Privacy policy accessible and accurate
+- [ ] Breach notification process documented (72h for GDPR)
+- [ ] DPA with third-party processors
+- [ ] No PII in logs, error messages, or analytics
+- [ ] Data encrypted at rest and in transit
+
+```python
+# GDPR: right to deletion
+@app.delete("/api/users/me")
+async def delete_account(user: User = Depends(get_current_user)):
+    await db.users.anonymize(user.id)
+    await db.sessions.revoke_all(user.id)
+    await audit_log.record("account_deleted", user.id)
+    return {"status": "account deleted"}
+
+# GDPR: data export
+@app.get("/api/users/me/export")
+async def export_data(user: User = Depends(get_current_user)):
+    data = await db.users.get_all_data(user.id)
+    return JSONResponse(content=data, headers={
+        "Content-Disposition": f"attachment; filename=data_{user.id}.json"
+    })
+```
+
+## OWASP ASVS
+
+### Level 1 — Minimum
+- [ ] All inputs validated server-side
+- [ ] Output encoding prevents XSS
+- [ ] Parameterized queries prevent injection
+- [ ] Secure auth defaults
+- [ ] Secure session management
+- [ ] Error handling doesn't leak info
+
+### Level 2 — Standard (SaaS)
+- [ ] All Level 1 + MFA available
+- [ ] Security headers configured
+- [ ] API rate limiting
+- [ ] Dependency scanning automated
+- [ ] Security logging and monitoring
+- [ ] File upload validation (type, size, content)
+
+## SOC 2 Basics
+- [ ] Access controls documented and enforced
+- [ ] Audit trail for sensitive operations
+- [ ] Incident response plan exists
+- [ ] Data backup and recovery tested
+- [ ] Change management process (PRs, reviews)
+- [ ] Least privilege access for employees
+
+## PCI DSS (Payment)
+- [ ] Card data encrypted in transit and at rest
+- [ ] No card numbers stored post-authorization (tokenize)
+- [ ] Access to cardholder data restricted by business need
+- [ ] Unique IDs for all users with system access
+- [ ] Regular vulnerability scans
+- [ ] Network segmented (cardholder zone isolated)
+
+## Scan Process
+1. Scan codebase for PII patterns (email, phone, name, IP)
+2. Check if PII storage has encryption and retention policy
+3. Verify deletion and export endpoints exist
+4. Confirm security headers and auth are configured
+5. Flag compliance gaps with severity and remediation