codingbuddy-rules 4.2.0 → 4.4.0

package/.ai-rules/skills/rule-authoring/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: rule-authoring
+description: Use when writing AI coding rules for codingbuddy that must work consistently across multiple AI tools (Cursor, Claude Code, Codex, GitHub Copilot, Amazon Q, Kiro). Covers rule clarity, trigger design, and multi-tool compatibility.
+---
+
+# Rule Authoring
+
+## Overview
+
+AI coding rules are instructions that shape how AI assistants behave. Poorly written rules are ignored, misinterpreted, or cause inconsistent behavior across tools.
+
+**Core principle:** Rules must be unambiguous, actionable, and testable. If an AI assistant can interpret a rule two different ways, it will choose the wrong one at the worst moment.
+
+**Iron Law:**
+```
+EVERY RULE MUST HAVE A TESTABLE "DID IT WORK?" CRITERION
+```
+
+## When to Use
+
+- Writing new rules for `.ai-rules/rules/`
+- Updating existing rules that produce inconsistent behavior
+- Adapting rules for a new AI tool (cursor, codex, q, kiro)
+- Auditing rules for ambiguity or overlap
+
+## Rule Quality Criteria
+
+A good rule is:
+
+| Quality | Bad Example | Good Example |
+|---------|-------------|--------------|
+| **Specific** | "Write good code" | "Functions must have a single return type" |
+| **Actionable** | "Be careful with auth" | "All endpoints must check authentication before executing" |
+| **Testable** | "Follow best practices" | "Test coverage must be ≥ 80% for new files" |
+| **Bounded** | "Always use TypeScript" | "Use TypeScript strict mode in all .ts files" |
+| **Non-overlapping** | Two rules about the same thing | One rule per concern |
+
+## Rule Structure
+
+### Core Rule Format
+
+```markdown
+## [Rule Category]: [Rule Name]
+
+**When:** [Trigger condition — when does this rule apply?]
+
+**Do:** [Specific action to take]
+
+**Don't:** [Specific anti-pattern to avoid]
+
+**Example:**
+\`\`\`typescript
+// ✅ Good
+function getUser(id: string): Promise<User>
+
+// ❌ Bad
+function getUser(id: any): any
+\`\`\`
+
+**Why:** [One-sentence rationale]
+```
+
+### Rule File Structure
+
+```markdown
+# [Category Name]
+
+Brief description of what rules in this file govern.
+
+## Rules
+
+### Rule 1: [Name]
+...
+
+### Rule 2: [Name]
+...
+
+## Rationale
+
+Why these rules exist for this project.
+
+## Exceptions
+
+Cases where these rules do not apply (keep this list short).
+```
+
+## Writing Process
+
+### Phase 1: Identify the Rule Need
+
+```
+1. What behavior is inconsistent or incorrect?
+   → "AI assistants sometimes use 'any' type in TypeScript"
+
+2. What is the desired behavior?
+   → "All variables must have explicit types"
+
+3. What is the trigger condition?
+   → "When writing TypeScript code"
+
+4. Can an AI verify compliance?
+   → "Yes: TypeScript compiler will error on 'any' in strict mode"
+
+5. Is there already a rule covering this?
+   → Check existing rules in .ai-rules/rules/
+```
+
+### Phase 2: Write the Rule
+
+**Template:**
+```markdown
+### [Rule Name]
+
+**When:** [Specific trigger condition]
+
+**Do:** [Concrete action in imperative mood]
+
+**Don't:** [Specific anti-pattern]
+
+**Check:** [How to verify the rule was followed]
+```
+
+**Good examples:**
+```markdown
+### No `any` Type
+
+**When:** Writing TypeScript code
+
+**Do:** Always specify explicit types for function parameters and return values
+
+**Don't:** Use `any` type — use `unknown` for truly unknown types, then narrow
+
+**Check:** TypeScript compiler passes with `noImplicitAny: true` in tsconfig
+
+---
+
+### Test Before Implement (TDD)
+
+**When:** Implementing a new function or feature
+
+**Do:** Write the failing test first, then write minimal implementation to pass it
+
+**Don't:** Write implementation first and add tests after
+
+**Check:** Running tests shows RED (failure) before GREEN (pass)
+```
+
+### Phase 3: Test Multi-Tool Compatibility
+
+Different AI tools parse rules differently. Test your rules with each tool:
+
+```
+Compatibility checklist for each new rule:
+
+Claude Code:
+- [ ] Rule triggers correctly from CLAUDE.md or custom-instructions.md
+- [ ] Rule doesn't conflict with default Claude behavior
+
+Cursor:
+- [ ] Rule works in .cursorrules or .cursor/rules/
+- [ ] Pattern matching works as expected
+
+GitHub Copilot / Codex:
+- [ ] Rule understandable from .github/copilot-instructions.md
+- [ ] No Copilot-specific syntax required
+
+Amazon Q:
+- [ ] Compatible with .q/rules/ format
+
+Kiro:
+- [ ] Compatible with .kiro/ format
+```
+
+### Phase 4: Anti-Ambiguity Review
+
+Read each rule and ask: "Could this be interpreted two different ways?"
+
+**Ambiguity red flags:**
+```
+❌ "appropriate" → What's appropriate? Define it.
+❌ "when necessary" → When is that? Specify the condition.
+❌ "best practices" → Which ones? List them.
+❌ "avoid" → How strongly? Use "never" or "prefer X over Y".
+❌ "clean code" → What does clean mean? Measurable criteria only.
+```
+
+**Ambiguity fixes:**
+```
+❌ "Use appropriate error handling"
+✅ "Catch specific error types, never catch Exception or Error base class"
+
+❌ "Write clean functions"
+✅ "Functions must be ≤ 30 lines and have a single return type"
+
+❌ "When necessary, add comments"
+✅ "Add comments only for non-obvious logic. Self-documenting code needs no comments."
+```
+
+## Rule Categories
+
+| Category | File | Covers |
+|----------|------|--------|
+| Core workflow | `rules/core.md` | PLAN/ACT/EVAL modes, TDD |
+| Project | `rules/project.md` | Tech stack, architecture |
+| Augmented coding | `rules/augmented-coding.md` | Code quality, testing |
+
+## Adapter-Specific Formatting
+
+### Claude Code (`adapters/claude-code.md`)
+
+```markdown
+## Claude Code Specific Rules
+
+- Use `parse_mode` for PLAN/ACT/EVAL detection
+- Follow `dispatch_agents` pattern for parallel agents
+- Context persists via `docs/codingbuddy/context.md`
+```
+
+### Cursor (`adapters/cursor.md`)
+
+```markdown
+## Cursor-Specific Rules
+
+Rules in `.cursorrules` are parsed line-by-line.
+Keep rules to one line each for Cursor compatibility.
+```
+
+### Codex (`adapters/codex.md`)
+
+```markdown
+## GitHub Copilot / Codex Rules
+
+Place in `.github/copilot-instructions.md`.
+Copilot prefers explicit examples over abstract rules.
+```
+
+## Rule Maintenance
+
+### Auditing Existing Rules
+
+```bash
+# Find rules that haven't been updated recently
+git log --since="6 months ago" -- packages/rules/.ai-rules/rules/
+
+# Find duplicate rule concepts
+grep -h "^###" packages/rules/.ai-rules/rules/*.md | sort | uniq -d
+```
+
+**Quarterly audit questions:**
+1. Is this rule still relevant to our current stack?
+2. Is this rule being followed consistently?
+3. Does this rule conflict with any new tool defaults?
+4. Are there new patterns that need new rules?
+
+## Quick Reference
+
+```
+Rule Strength Vocabulary:
+─────────────────────────
+MUST / ALWAYS     → Required, no exceptions
+SHOULD / PREFER   → Default behavior, exceptions allowed
+AVOID / PREFER NOT → Discouraged, explain if used
+NEVER / MUST NOT  → Prohibited
+```
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "This rule is obvious" | Write it anyway — different AI tools need explicit guidance |
+| "The existing rule covers this" | Check carefully — overlap causes conflicts |
+| "Rules don't need testing" | Test with each target AI tool |
+| "Abstract rules are more flexible" | Abstract rules are ignored or misapplied |

package/.ai-rules/skills/security-audit/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: security-audit
+description: Use when reviewing code for security vulnerabilities, before shipping features, or conducting security assessments. Covers OWASP Top 10, secrets exposure, authentication, and authorization flaws.
+---
+
+# Security Audit
+
+## Overview
+
+Security vulnerabilities are invisible until exploited. This skill provides a systematic approach to finding them before attackers do.
+
+**Core principle:** ASSUME BREACH. Review every input, every output, every boundary.
+
+**Iron Law:**
+```
+NO SECURITY REVIEW WITHOUT THREAT MODELING FIRST
+```
+
+## When to Use
+
+- Before merging any authentication or authorization code
+- Before shipping features that handle user data
+- When adding third-party dependencies
+- After environment variable / secrets changes
+- Periodic security sweeps on production code
+- Reviewing MCP server endpoints (especially SSE/HTTP transport)
+
+## The Four Phases
+
+### Phase 1: Threat Modeling
+
+**Before reviewing any code:**
+
+1. **Identify Assets** — What are we protecting? (user data, tokens, credentials, business logic)
+2. **Identify Attack Surfaces** — HTTP endpoints, file uploads, environment vars, third-party integrations
+3. **Identify Threat Actors** — External attackers, malicious insiders, compromised dependencies
+4. **Map Data Flow** — Where does sensitive data enter, travel, and exit?
+
+### Phase 2: OWASP Top 10 Checklist
+
+Work through each category systematically:
+
+#### A01: Broken Access Control
+```
+- [ ] Every endpoint checks authentication
+- [ ] Authorization verified per-resource, not just per-route
+- [ ] IDOR: Can user A access user B's data by changing ID?
+- [ ] Admin routes protected from regular users
+- [ ] CORS policy restricts allowed origins
+```
+
+#### A02: Cryptographic Failures
+```
+- [ ] No plaintext passwords stored
+- [ ] Sensitive data encrypted at rest (PII, tokens, keys)
+- [ ] TLS enforced for all connections
+- [ ] Weak algorithms absent (MD5, SHA1 for passwords, DES)
+- [ ] Secrets not in code, logs, or URLs
+```
+
+#### A03: Injection
+```sql
+-- ❌ SQL Injection vulnerable
+db.query(`SELECT * FROM users WHERE id = ${userId}`);
+
+-- ✅ Parameterized
+db.query('SELECT * FROM users WHERE id = ?', [userId]);
+```
+
+```typescript
+// ❌ Command Injection
+exec(`ls ${userInput}`);
+
+// ✅ Safe
+execFile('ls', [userInput]);
+```
+
+```typescript
+// ❌ XSS
+element.innerHTML = userInput;
+
+// ✅ Safe
+element.textContent = userInput;
+```
+
+#### A04: Insecure Design
+```
+- [ ] Rate limiting on sensitive endpoints (login, password reset)
+- [ ] Account lockout after failed attempts
+- [ ] Password reset tokens expire (< 15 minutes)
+- [ ] Sensitive operations require re-authentication
+```
+
+#### A05: Security Misconfiguration
+```
+- [ ] Debug mode disabled in production
+- [ ] Default credentials changed
+- [ ] Unnecessary features/endpoints disabled
+- [ ] Security headers present (CSP, HSTS, X-Frame-Options)
+- [ ] Error messages don't expose stack traces to users
+```
+
+#### A06: Vulnerable Components
+```bash
+# Check for known CVEs
+npm audit
+yarn audit
+
+# Check for outdated packages with vulnerabilities
+npx audit-ci --moderate
+```
+
+#### A07: Authentication Failures
+```
+- [ ] Session IDs invalidated on logout
+- [ ] JWT secrets sufficiently random (>= 256 bits)
+- [ ] JWT expiry set appropriately (access: minutes, refresh: days)
+- [ ] Brute force protection on login
+- [ ] Multi-factor authentication available for sensitive actions
+```
+
+#### A08: Software Integrity Failures
+```
+- [ ] Dependencies pinned to exact versions
+- [ ] Subresource integrity (SRI) for CDN assets
+- [ ] CI/CD pipeline secured (no untrusted code execution)
+- [ ] Package signatures verified where possible
+```
+
+#### A09: Logging Failures
+```
+- [ ] Authentication events logged (success + failure)
+- [ ] Authorization failures logged
+- [ ] No sensitive data (passwords, tokens, PII) in logs
+- [ ] Log tampering prevented
+- [ ] Alerts set for suspicious patterns
+```
+
+#### A10: Server-Side Request Forgery (SSRF)
+```
+- [ ] User-supplied URLs validated against allowlist
+- [ ] Internal network addresses blocked from user input
+- [ ] DNS rebinding protection
+```
+
+### Phase 3: Secrets & Credentials Scan
+
+```bash
+# Scan for hardcoded secrets
+grep -rn "password\|secret\|token\|api_key\|apikey\|private_key" \
+  --include="*.ts" --include="*.js" --include="*.env*" \
+  --exclude-dir=node_modules .
+
+# Check .gitignore covers sensitive files
+cat .gitignore | grep -E "\.env|\.key|credentials"
+
+# Verify no secrets in git history
+git log --all --full-history -- "*.env" "*.key" "credentials*"
+```
+
+**Common secret patterns to find:**
+```
+❌ const API_KEY = "sk-abc123..."
+❌ password: "admin123"
+❌ Authorization: "Bearer eyJ..."  (hardcoded)
+❌ connectionString = "mongodb://user:pass@host"
+
+✅ const API_KEY = process.env.API_KEY
+✅ password: process.env.DB_PASSWORD
+```
+
+### Phase 4: MCP Server Specific (codingbuddy)
+
+For MCP servers using SSE/HTTP transport:
+
+```typescript
+// ❌ No authentication
+app.use('/sse', sseHandler);
+
+// ✅ Bearer token validation
+app.use('/sse', (req, res, next) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (process.env.MCP_SSE_TOKEN && token !== process.env.MCP_SSE_TOKEN) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+  next();
+});
+```
+
+```
+- [ ] SSE endpoint authenticates when MCP_SSE_TOKEN is set
+- [ ] CORS configured for trusted origins only
+- [ ] Rate limiting on MCP tool calls
+- [ ] Input validation on all tool parameters
+- [ ] No sensitive data in MCP resource URIs
+```
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "We're not a target" | Every internet-facing system is a target |
+| "This is internal only" | Insider threats are real; internal ≠ trusted |
+| "The framework handles it" | Frameworks have defaults that must be configured |
+| "We'll add security later" | Retrofitting security costs 10× more |
+| "Tests don't cover security" | Security requires dedicated review, not just tests |
+
+## Quick Reference
+
+| Category | Check | Tool |
+|----------|-------|------|
+| Dependencies | CVE scan | `npm audit` |
+| Secrets | Hardcoded creds | grep + git-secrets |
+| Injection | SQL, XSS, Command | Manual + ESLint |
+| Auth | JWT, sessions | Manual review |
+| Headers | CSP, HSTS | securityheaders.com |
+| OWASP | Top 10 | ZAP, Burp Suite |
+
+## Output Format
+
+Document findings as:
+
+```markdown
+## Security Audit Report — YYYY-MM-DD
+
+### Critical (fix before deploy)
+- [ ] SQL injection in /api/users endpoint (line 42, users.service.ts)
+
+### High (fix within 24h)
+- [ ] JWT secret too short (< 256 bits)
+
+### Medium (fix this sprint)
+- [ ] Missing rate limiting on /auth/login
+
+### Low (backlog)
+- [ ] Verbose error messages in development mode
+
+### Passed Checks
+- [x] No hardcoded secrets found
+- [x] All endpoints require authentication
+```