@caddis/cli 0.3.0 → 0.4.1

package/bundles/codex/.codex/skills/coding/backend-development/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: backend-development
+description: Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture.
+source: wshobson/agents
+license: MIT
+---
+
+# Backend Development
+
+## API Design
+
+### RESTful Conventions
+```
+GET    /users          # List users
+POST   /users          # Create user
+GET    /users/:id      # Get user
+PUT    /users/:id      # Update user (full)
+PATCH  /users/:id      # Update user (partial)
+DELETE /users/:id      # Delete user
+
+GET    /users/:id/posts  # List user's posts
+POST   /users/:id/posts  # Create post for user
+```
+
+### Response Format
+```json
+{
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 100
+  }
+}
+```
+
+### Error Format
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      { "field": "email", "message": "Invalid format" }
+    ]
+  }
+}
+```
+
+## Database Patterns
+
+### Schema Design
+```sql
+-- Use UUIDs for public IDs
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  public_id UUID DEFAULT gen_random_uuid() UNIQUE,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Soft deletes
+ALTER TABLE users ADD COLUMN deleted_at TIMESTAMPTZ;
+
+-- Indexes
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_created ON users(created_at DESC);
+```
+
+### Query Patterns
+```sql
+-- Pagination with cursor
+SELECT * FROM posts
+WHERE created_at < $cursor
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- Efficient counting
+SELECT reltuples::bigint AS estimate
+FROM pg_class WHERE relname = 'users';
+```
+
+## Authentication
+
+### JWT Pattern
+```typescript
+interface TokenPayload {
+  sub: string;      // User ID
+  iat: number;      // Issued at
+  exp: number;      // Expiration
+  scope: string[];  // Permissions
+}
+
+function verifyToken(token: string): TokenPayload {
+  return jwt.verify(token, SECRET) as TokenPayload;
+}
+```
+
+### Middleware
+```typescript
+async function authenticate(req: Request, res: Response, next: Next) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (!token) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  try {
+    req.user = verifyToken(token);
+    next();
+  } catch {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+}
+```
+
+## Caching Strategy
+
+```typescript
+// Cache-aside pattern
+async function getUser(id: string): Promise<User> {
+  const cached = await redis.get(`user:${id}`);
+  if (cached) return JSON.parse(cached);
+
+  const user = await db.users.findById(id);
+  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
+  return user;
+}
+
+// Cache invalidation
+async function updateUser(id: string, data: Partial<User>) {
+  await db.users.update(id, data);
+  await redis.del(`user:${id}`);
+}
+```
+
+## Architecture Patterns
+
+### Repository Pattern
+Abstract data access from business logic for testability and swappable backends.
+
+```typescript
+interface UserRepository {
+  findAll(filters?: UserFilters): Promise<User[]>
+  findById(id: string): Promise<User | null>
+  create(data: CreateUserDto): Promise<User>
+  update(id: string, data: UpdateUserDto): Promise<User>
+  delete(id: string): Promise<void>
+}
+```
+
+### Service Layer Pattern
+Separate business logic from data access and HTTP concerns.
+
+```typescript
+class UserService {
+  constructor(private userRepo: UserRepository) {}
+
+  async createUser(data: CreateUserDto): Promise<User> {
+    // Business logic: validation, enrichment, side effects
+    const existing = await this.userRepo.findByEmail(data.email);
+    if (existing) throw new ConflictError('Email already registered');
+    return this.userRepo.create(data);
+  }
+}
+```
+
+### N+1 Query Prevention
+```typescript
+// Bad: N+1 queries
+const posts = await getPosts();
+for (const post of posts) {
+  post.author = await getUser(post.author_id);  // N queries
+}
+
+// Good: Batch fetch
+const posts = await getPosts();
+const authorIds = posts.map(p => p.author_id);
+const authors = await getUsers(authorIds);  // 1 query
+const authorMap = new Map(authors.map(a => [a.id, a]));
+posts.forEach(post => { post.author = authorMap.get(post.author_id); });
+```
+
+## Rate Limiting
+
+```typescript
+// Library-based approach
+const limiter = rateLimit({
+  windowMs: 60 * 1000,  // 1 minute
+  max: 100,             // 100 requests per window
+  keyGenerator: (req) => req.ip,
+  handler: (req, res) => {
+    res.status(429).json({ error: 'Too many requests' });
+  }
+});
+```
+
+## Error Handling
+
+### Retry with Exponential Backoff
+```typescript
+async function fetchWithRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3
+): Promise<T> {
+  let lastError: Error;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      if (i < maxRetries - 1) {
+        const delay = Math.pow(2, i) * 1000;
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError!;
+}
+```
+
+### Centralized Error Handler
+```typescript
+class ApiError extends Error {
+  constructor(public statusCode: number, message: string, public isOperational = true) {
+    super(message);
+  }
+}
+
+function errorHandler(error: unknown, req: Request): Response {
+  if (error instanceof ApiError) {
+    return json({ error: error.message }, { status: error.statusCode });
+  }
+  if (error instanceof z.ZodError) {
+    return json({ error: 'Validation failed', details: error.errors }, { status: 400 });
+  }
+  console.error('Unexpected error:', error);
+  return json({ error: 'Internal server error' }, { status: 500 });
+}
+```
+
+## Role-Based Access Control
+
+```typescript
+type Permission = 'read' | 'write' | 'delete' | 'admin';
+
+const rolePermissions: Record<string, Permission[]> = {
+  admin: ['read', 'write', 'delete', 'admin'],
+  moderator: ['read', 'write', 'delete'],
+  user: ['read', 'write']
+};
+
+function hasPermission(user: { role: string }, permission: Permission): boolean {
+  return (rolePermissions[user.role] || []).includes(permission);
+}
+```
+
+## Background Jobs and Queues
+
+```typescript
+class JobQueue<T> {
+  private queue: T[] = [];
+  private processing = false;
+
+  async add(job: T): Promise<void> {
+    this.queue.push(job);
+    if (!this.processing) this.process();
+  }
+
+  private async process(): Promise<void> {
+    this.processing = true;
+    while (this.queue.length > 0) {
+      const job = this.queue.shift()!;
+      try { await this.execute(job); }
+      catch (error) { console.error('Job failed:', error); }
+    }
+    this.processing = false;
+  }
+
+  private async execute(job: T): Promise<void> { /* implementation */ }
+}
+```
+
+## Observability
+
+### Structured Logging
+```typescript
+class Logger {
+  log(level: 'info' | 'warn' | 'error', message: string, context?: Record<string, unknown>) {
+    console.log(JSON.stringify({
+      timestamp: new Date().toISOString(), level, message, ...context
+    }));
+  }
+  info(msg: string, ctx?: Record<string, unknown>) { this.log('info', msg, ctx); }
+  warn(msg: string, ctx?: Record<string, unknown>) { this.log('warn', msg, ctx); }
+  error(msg: string, err: Error, ctx?: Record<string, unknown>) {
+    this.log('error', msg, { ...ctx, error: err.message, stack: err.stack });
+  }
+}
+```
+
+### Health and Monitoring
+- **Metrics**: Request latency, error rates, queue depths
+- **Tracing**: Distributed tracing with correlation IDs
+- **Health checks**: `/health` and `/ready` endpoints

package/bundles/codex/.codex/skills/coding/code-review/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: code-review
+context: fork
+description: Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits.
+source: anthropics/claude-code
+license: Apache-2.0
+---
+
+# Code Review
+
+> **On Claude Code, prefer the native `/code-review`.** It is a command, not a skill, so it always
+> fires — including headless — and it has grown capabilities this one does not have: effort levels
+> (`low`…`max`), an `ultra` mode that runs a multi-agent review in the cloud, `--comment` to post
+> findings as inline PR comments, and `--fix` to apply them to the working tree. Reach for it first.
+>
+> This surface remains because caddis ships to harnesses that have **no** native equivalent — agy,
+> Codex and Copilot. There it is the only review you get. Do not delete it to tidy up Claude Code.
+>
+> `/caddis:cross-review` is NOT replaced by either. It sends the diff to a **different vendor's**
+> model, which neither this nor the native reviewer can do.
+
+## Review Categories
+
+### 1. Security Review
+Check for:
+- SQL injection vulnerabilities
+- XSS (Cross-Site Scripting)
+- Command injection
+- Insecure deserialization
+- Hardcoded secrets/credentials
+- Improper authentication/authorization
+- Insecure direct object references
+
+### 2. Performance Review
+Check for:
+- N+1 queries
+- Missing database indexes
+- Unnecessary re-renders (React)
+- Memory leaks
+- Blocking operations in async code
+- Missing caching opportunities
+- Large bundle sizes
+
+### 3. Code Quality Review
+Check for:
+- Code duplication (DRY violations)
+- Functions doing too much (SRP violations)
+- Deep nesting / complex conditionals
+- Magic numbers/strings
+- Poor naming
+- Missing error handling
+- Incomplete type coverage
+
+### 4. Testing Review
+Check for:
+- Missing test coverage for new code
+- Tests that don't test behavior
+- Flaky test patterns
+- Missing edge cases
+- Mocked external dependencies
+
+## Review Output Format
+
+```markdown
+## Code Review Summary
+
+### 🔴 Critical (Must Fix)
+- **[File:Line]** [Issue description]
+  - **Why:** [Explanation]
+  - **Fix:** [Suggested fix]
+
+### 🟡 Suggestions (Should Consider)
+- **[File:Line]** [Issue description]
+  - **Why:** [Explanation]
+  - **Fix:** [Suggested fix]
+
+### 🟢 Nits (Optional)
+- **[File:Line]** [Minor suggestion]
+
+### ✅ What's Good
+- [Positive feedback on good patterns]
+```
+
+## Common Patterns to Flag
+
+### Security
+```javascript
+// BAD: SQL injection
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD: Parameterized query
+const query = 'SELECT * FROM users WHERE id = $1';
+await db.query(query, [userId]);
+```
+
+### Performance
+```javascript
+// BAD: N+1 query
+users.forEach(async user => {
+  const posts = await getPosts(user.id);
+});
+
+// GOOD: Batch query
+const userIds = users.map(u => u.id);
+const posts = await getPostsForUsers(userIds);
+```
+
+### Error Handling
+```javascript
+// BAD: Swallowing errors
+try {
+  await riskyOperation();
+} catch (e) {}
+
+// GOOD: Handle or propagate
+try {
+  await riskyOperation();
+} catch (e) {
+  logger.error('Operation failed', { error: e });
+  throw new AppError('Operation failed', { cause: e });
+}
+```
+
+## Review Checklist
+
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] Error handling complete
+- [ ] Types/interfaces defined
+- [ ] Tests added for new code
+- [ ] No obvious performance issues
+- [ ] Code is readable and documented
+- [ ] Breaking changes documented
+
+## Machine Verdict (automated / headless runs)
+
+**Then, as the very last line of your output (nothing after it), emit the machine verdict:**
+`REVIEW: CLEAN` (no blocking issues found across the categories above) or `REVIEW: BLOCKING` (one
+or more blocking issues). Automated runners read only this line; it must exactly match one of
+those two forms.

package/bundles/codex/.codex/skills/coding/codebase-audit/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: codebase-audit
+context: fork
+description: Systematic codebase audit methodology for unfamiliar codebases before architecture or implementation work. Use for new codebase, unfamiliar codebase, pre-implementation audit, codebase review, technical due diligence, or onboarding to an existing project. Produces AUDIT-FINDINGS.md and QUESTIONS.md. Routes to Architect, Planner, or Code Reviewer agents.
+---
+
+# Codebase Audit Skill
+
+Systematic 6-step audit for entering an unfamiliar codebase before architecture changes, major features, or refactoring. Do not guess patterns — audit first.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- "I'm new to this codebase"
+- "Audit this project before we start building"
+- "I need to understand what's here before changing it"
+- "Pre-implementation review"
+- Any major feature in a codebase you haven't worked in this session
+
+**Do not skip the audit** even when the task seems small — hidden coupling causes broken assumptions.
+
+## 2. Audit Scope — 20 Areas
+
+| # | Area | What to Look For |
+|---|---|---|
+| 1 | **Architecture** | Monolith/microservice/monorepo, layer separation, module boundaries |
+| 2 | **Entry Points** | Main files, router setup, CLI entry, exports index |
+| 3 | **Framework & Runtime** | React version, Next.js, FastAPI, Django, Node version, Python version |
+| 4 | **Dependencies** | `package.json`/`pyproject.toml` — packages, versions, peer deps, outdated |
+| 5 | **Code Quality** | Lint config, formatter, TypeScript strict mode, type coverage |
+| 6 | **Testing** | Test runner, coverage %, which layers are tested, missing tests |
+| 7 | **Security Posture** | Auth implementation, env var usage, hardcoded secrets, CORS |
+| 8 | **Documentation** | README completeness, inline comments, API docs |
+| 9 | **Performance Signals** | Caching, lazy loading, database indexes, N+1 queries |
+| 10 | **DevOps / CI** | Build commands, CI config, deployment method, Dockerfile |
+| 11 | **API Design** | REST conventions, versioning, error response format, input validation |
+| 12 | **Data Layer** | ORM vs raw SQL, migration strategy, schema location |
+| 13 | **State Management** | Client state (Zustand, Redux, Context), server state (React Query) |
+| 14 | **Error Handling** | Global error boundary, unhandled promise rejections, logging |
+| 15 | **Environment Config** | `.env.example`, `pydantic-settings`, config validation on startup |
+| 16 | **Dead Code / Tech Debt** | TODOs, commented-out code, unused packages, deprecated calls |
+| 17 | **Naming Conventions** | Consistent file/folder naming, component vs module patterns |
+| 18 | **Shared Libraries** | Utility functions, hooks, services — shared vs duplicated |
+| 19 | **Accessibility** | ARIA usage, keyboard nav, color contrast, skip-nav |
+| 20 | **Observability** | Logging format, tracing, health endpoints, error reporting |
+
+## 3. 6-Step Audit Method
+
+### Step 1 — Map the Repository
+```
+actions:
+  - List top-level directories and understand intent of each
+  - Identify the project type (app, library, monorepo, microservice)
+  - Read README.md fully — note setup instructions, known issues
+  - Check for CONTRIBUTING.md, ARCHITECTURE.md, or ADR folders
+```
+
+### Step 2 — Find Entry Points
+```
+actions:
+  - Identify main application entry (main.py, app.py, src/index.ts, src/main.ts)
+  - Trace the request lifecycle from entry to response (1 complete path)
+  - Identify router/controller/handler layers
+  - Find test entry (jest.config.ts, vite.config.ts, pytest.ini/pyproject.toml)
+  - Find build entry (package.json scripts, Makefile, Dockerfile)
+```
+
+### Step 3 — Dependencies and Versions
+```
+actions:
+  - Read package.json / pyproject.toml — note major dependencies and versions
+  - Check for deprecated or significantly outdated packages
+  - Identify direct vs transitive dependency conflicts
+  - Note peer dependency version mismatches
+  - Check for security advisories (mental note or npm audit / pip-audit)
+```
+
+### Step 4 — Audit by Severity
+```
+For each area in §2, assign:
+  🔴 CRITICAL — Security vulnerability, data loss risk, broken functionality
+  🟡 WARNING  — Performance issue, tech debt, missing validation
+  🟢 NOTE     — Style inconsistency, minor improvement opportunity
+  ⚪ OK       — Meets expectations, no action needed
+```
+
+### Step 5 — Compile Questions
+```
+For every assumption or ambiguity discovered:
+  - Business context: "Why does X exist? Is it still needed?"
+  - Architecture: "Is this pattern intentional or historical?"
+  - Implementation: "Is there a newer pattern preferred for this?"
+  - Scope: "Which areas are off-limits for this change?"
+```
+
+### Step 6 — Write Deliverables
+Write two files in the project root (or `docs/` if it exists):
+- `AUDIT-FINDINGS.md`
+- `QUESTIONS.md`
+
+## 4. Output Templates
+
+### `AUDIT-FINDINGS.md`
+```markdown
+# Codebase Audit Findings
+
+**Project**: [name]
+**Audited**: [date]
+**Scope**: [what was covered]
+
+## Summary
+[2–3 sentence high-level assessment]
+
+## Critical Findings 🔴
+
+### CRIT-001: [Title]
+**File**: `path/to/file.ts` (line N)
+**Issue**: [What is wrong and why]
+**Risk**: [What can go wrong]
+**Recommendation**: [Specific fix]
+
+## Warnings 🟡
+
+### WARN-001: [Title]
+**File**: `path/to/file.py`
+**Issue**: [What needs attention]
+**Recommendation**: [Specific improvement]
+
+## Notes 🟢
+
+- [Minor observations, style, preferences]
+
+## Architecture Overview
+[Brief description of what was found — layers, patterns, notable design decisions]
+
+## Scope for Current Task
+Based on the requested change, these areas are in scope: …
+These areas should NOT be touched: …
+```
+
+### `QUESTIONS.md`
+```markdown
+# Pre-Implementation Questions
+
+**For**: [next agent or human reviewer]
+**Context**: [what we're about to build]
+
+## Blocking Questions (must answer before code changes)
+
+### Q1: [Question]
+**Context**: [why this matters]
+**Impact if wrong**: [what breaks]
+
+### Q2: [Question]
+
+## Advisory Questions (inform decisions but don't block)
+
+### Q3: [Question]
+
+## Assumptions Made
+If we proceed without answers, these assumptions apply:
+- [assumption 1]
+- [assumption 2]
+```
+
+## 5. Severity Tags
+
+| Tag | Code | Meaning |
+|---|---|---|
+| 🔴 Critical | `CRIT-NNN` | Fix before any changes proceed |
+| 🟡 Warning | `WARN-NNN` | Address in current or next sprint |
+| 🟢 Note | `NOTE-NNN` | Backlog item or stylistic observation |
+| ⚪ OK | — | No action needed |
+
+## 6. Handoff Guidance
+
+After completing the audit:
+
+| Finding Type | Route To |
+|---|---|
+| Architecture redesign needed | `@Architect` — provide `AUDIT-FINDINGS.md` |
+| Implementation can proceed with caution | `@Planner` — provide findings + questions |
+| Major quality/security issues | `@Code-Reviewer` + `@Security-Analyst` |
+| Only minor notes, clear path | Proceed directly with `@Implement` or `@Anchor` |
+
+### Prompt template for handoff:
+```
+@[Agent]: I've completed a codebase audit. 
+Findings: [link or inline AUDIT-FINDINGS.md]
+Blocking questions: [key Q from QUESTIONS.md]
+The task is: [original task description]
+Please [design solution / create plan / review / implement] with these findings in mind.
+```
+
+## 7. Checklist
+
+- [ ] README.md read fully
+- [ ] Entry point traced end-to-end (one complete request/render cycle)
+- [ ] All 20 audit areas assessed (even if just ⚪ OK)
+- [ ] Critical findings have file + line citation
+- [ ] `AUDIT-FINDINGS.md` written to disk
+- [ ] `QUESTIONS.md` written to disk
+- [ ] Blocking questions identified separately
+- [ ] Agent handoff prompt prepared