@caddis/cli 0.2.6 → 0.4.0

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

package/bundles/codex/.codex/skills/coding/dashboard-perf-sweep/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: dashboard-perf-sweep
+context: fork
+description: Re-measure an app's dashboard/API endpoints for load-time regressions and decide, with a documented checklist (not a black-box verdict), whether a slow one is a candidate for the rs-kit summary-table refresher pattern — or needs an index, keyset paging, gzip, or nothing at all. Use when the user says "sweep dashboard performance", "check if this app needs rs-kit", "re-measure the perf tracker", "is this endpoint a refresher candidate", or when a dashboard-performance-tracker.md is stale and needs re-validating. Read-only by default (dev servers only; prod requires an explicit opt-in and human confirmation) and human-invoked, never scheduled -- it surfaces candidates, it does not enroll them.
+---
+
+# dashboard-perf-sweep — re-measure, then judge the shape, not just the time
+
+Today an app "earns" the rs-kit refresher pattern only when someone happens to be doing unrelated
+work on it, hits a slow page, and measures it properly. That worked for a couple of apps in the
+fleet, but a snapshot measurement goes stale — a page added last month, or a table that crossed a
+growth threshold since, has no mechanism to surface itself. This skill re-measures on demand.
+
+**What already exists and must NOT be rebuilt:** every app in the fleet has its own
+`.caddis/kb/dashboard-performance-tracker.md` with real baseline measurements. The gap this closes
+is **re-measurement and re-judgment**, not first-time discovery.
+
+## Explicit scope guardrails — do not relax without a new conversation
+
+- **Read-only except the final tracker update.** No code changes, no schema changes, ever. The only
+  write this skill makes is a diffable update to the target app's own `dashboard-performance-tracker.md`.
+- **Dev by default.** Measuring against prod requires an explicit opt-in flag from the user AND, per
+  this project's convention for risky/hard-to-reverse actions, confirmation before hitting a live
+  service.
+- **Human-invoked, not scheduled.** Run this when a person chooses to — never wire it into a cron job
+  or background automation. It surfaces candidates; it does not enroll them.
+- **rs-kit is one of several possible recommendations, never the only output.** The checklist below
+  must be able to conclude "needs an index," "needs keyset paging," "needs gzip/trimmed fields,"
+  "not currently a candidate" — recommending rs-kit only for the specific aggregation shape.
+
+## The decision model — two gates, not one number
+
+**Gate 1 — time (mechanical).** `DASHBOARD-PERFORMANCE-STANDARD.md` Rule 6: the first, uncached load
+of any dashboard endpoint must finish in **under ~1 second**. The harness script below applies this
+gate automatically per endpoint. Passing gate 1 does **not** mean rs-kit — it just means "look closer."
+
+**Gate 2 — shape (judgment, applied by you the agent, never automated).** rs-kit fixes exactly one
+shape: a query that recomputes `O(all rows ever stored)` per request, against data that keeps
+growing. Time alone is not sufficient evidence — the fleet's own history proves it:
+
+| App | Cold time | Root cause | rs-kit? |
+|---|---|---|---|
+| App A | worst >60s, 5 real breaches | recurring full-table aggregation | **YES** |
+| App B (pre-fix) | 14s–60s+ across several endpoints | recurring full-table aggregation | **YES** |
+| App C | 10.3s | a single ~158MB LOB payload on 9.1k rows, not aggregation | **NO** — SQL aggregate + gzip |
+| App D | 1.9s | cold JSON parse, no DB at all in prod | **NO** — warm the provider |
+| App E | 202ms | n/a — never crossed gate 1 | **NO** |
+
+A naive "slow ⇒ recommend rs-kit" tool would have wrongly flagged App C and App D. That already
+happened once before the shape distinction was made explicit — don't repeat it.
+
+## Step 1 — build the endpoint list for this app
+
+The tracker files are semi-structured (page names + backtick route fragments in a markdown table),
+not a clean machine-parseable list — extract the list yourself, per app, each run:
+
+1. Read the target app's `.caddis/kb/dashboard-performance-tracker.md` — pull every "Page / endpoint"
+   entry, in particular anything marked ⏳ pending or not re-measured recently.
+2. If the app has a `UI_PAGE_GUIDE.md` (check root and `docs/reference/`), cross-check it for pages
+   **not yet in the tracker** — this is what catches drift, not just re-running the same old list. Not
+   every app has one; if it's missing, say so explicitly rather than silently only using the tracker.
+3. Write the result as a JSON file matching the harness's input shape:
+   ```json
+   [
+     {"name": "Historical Trends chart", "method": "GET", "path": "/api/trends/daily"},
+     {"name": "IW grid", "method": "POST", "path": "/raworkbench/investigation/query", "json": {}}
+   ]
+   ```
+4. Confirm with the user (or the app's own `run`/`webapp-testing` conventions) how to reach the dev
+   instance safely, and what auth the endpoints need (open / token / session cookie) — pass it via
+   `--header`.
+
+## Step 2 — start the dev server, then run the harness
+
+Use the app's own `run` skill/convention to start it — this skill does not start dev servers itself,
+only measures an already-reachable URL.
+
+**Use `127.0.0.1`, never the hostname `localhost`, in `--base-url`.** On Windows, Python's `urllib`
+resolves `localhost` dual-stack (tries IPv6 `::1` first) and can add a **spurious, rock-steady
+~1000ms** to every single request — cold *and* warm, on every endpoint including the framework's own
+static docs page. It looks exactly like a real, uniform perf problem (equal cold/warm, present on
+trivial routes too) and is not one. This cost real time during this skill's own validation (§
+Validating below) before `127.0.0.1` was substituted and the true numbers — sub-15ms — appeared. If a
+sweep ever comes back with a suspiciously uniform floor across unrelated endpoints, first time a
+`/docs` or `/openapi.json` route on the same base URL before trusting the data.
+
+```bash
+python <skill-dir>/scripts/perf_sweep.py --base-url http://127.0.0.1:<port> --endpoints endpoints.json
+python <skill-dir>/scripts/perf_sweep.py --base-url http://127.0.0.1:<port> --endpoints endpoints.json \
+  --header "Cookie: session=..." --output report.json
+```
+
+Cold = first request after the dev server's fresh start (or right after a cache-bust if it can't be
+restarted cheaply); warm = the immediate second request. The report flags gate-1 breaches and prints
+the cold/warm ratio — a big ratio with no cache in between already points at a query-shape problem,
+not a cache-TTL one. **A page that errors or times out is a finding, not a script failure** — it's
+printed as `[ERROR]`, never silently dropped.
+
+## Step 3 — apply the gate-2 checklist to every gate-1 breach
+
+Force these questions, in order, for each slow endpoint — don't skip to a verdict:
+
+1. **Does response size explain most of the time** (large payload, not a slow query)? → not rs-kit;
+   recommend trimming fields / gzip / virtualization.
+2. **Is the slow part parsing/serialization, not the DB round-trip?** → not rs-kit; recommend
+   caching/warming the parsed form (App D precedent).
+3. **Does the query scale with total stored rows rather than the response size** — read the actual
+   SQL/query plan, not just the timing — **and is the same aggregation recomputed per request on data
+   that keeps growing?** → candidate for rs-kit.
+4. **Is it slow only at deep pagination (OFFSET)?** → not rs-kit; recommend keyset paging
+   (`exception_id`-style cursor, App B precedent).
+5. **Is a specific WHERE clause unseekable** (function-wrapped column, NVARCHAR/VARCHAR param
+   mismatch)? → not rs-kit; recommend an index or a param-type fix.
+
+Link findings to real fleet precedent (the table above, the `nvarchar-param-varchar-column-scan`
+pattern, the keyset-paging work) rather than describing fixes in the abstract — every category here
+has already been solved once in this fleet.
+
+## Step 4 — update the tracker, diffably
+
+Update the target app's own `dashboard-performance-tracker.md` in place with the new measurements and
+verdicts, so drift becomes visible over time in the diff. Never silently overwrite it without the user
+being able to see a before/after. Print a summary alongside the file edit.
+
+## Validating this skill against known ground truth
+
+Before trusting a new app's output, or after changing the checklist, run the sweep against two
+already-known apps in your fleet and confirm it reproduces the **already-established, human-verified**
+conclusion for each: one that's genuinely fast (should conclude "not a candidate") and one with a
+known aggregation breach (should conclude "aggregation-shaped, rs-kit candidate" for the pages
+already identified). If the output disagrees with the known-good conclusion for either, that's a
+checklist bug — fix the checklist, don't rationalize the disagreement away.