codexkit 1.0.0

package/.codex/skills/defense-in-depth/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: defense-in-depth
+description: Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible
+version: 1.0.0
+tags: [code-quality, debugging]
+dependencies: []
+---
+
+# Defense-in-Depth Validation
+
+> **Replaces** single-layer validation where bad data propagates silently until it causes cryptic failures deep in execution
+
+## When to Use
+
+- A bug is caused by invalid data flowing through multiple layers
+- One validation check is insufficient because data crosses boundaries
+
+## When NOT to Use
+
+- Simple, single-layer validation at an obvious entry point is enough
+- The issue is unrelated to invalid data or boundary checks
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Validating only at the entry point (trusting downstream) | Alternate paths and refactors bypass one gate | Add independent checks at each boundary |
+| Duplicating identical validation at every layer | Creates noise without improving safety | Tailor each layer to boundary-specific invariants |
+| Catching and swallowing errors silently | Hides failures and delays detection | Raise explicit errors with actionable context |
+| Mixing validation with business logic | Makes behavior hard to reason about and test | Keep validation checks explicit and separate from core logic |
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === "") {
+    throw new Error("workingDirectory cannot be empty");
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error("projectDir required for workspace initialization");
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === "test") {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(`Refusing git init outside temp dir during tests: ${directory}`);
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug("About to git init", {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs the others missed:
+
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.
+
+## Verification
+
+- Test with invalid input at each layer boundary — each should reject independently.
+- Remove one validation layer — the next layer should still catch the error.
+
+## See Also
+
+- **structured-edit** - Reliable read/verify/edit workflow when changing validation code across layers

package/.codex/skills/dependency-upgrades/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: dependency-upgrades
+description: Safe dependency upgrade process with risk tiers, validation gates, and rollback procedure.
+---
+
+# dependency-upgrades
+
+## Purpose
+Upgrade dependencies safely with explicit risk control, validated outcomes, and immediate rollback.
+
+## Use This Skill When
+- Addressing vulnerability alerts
+- Updating stale packages before release
+- Resolving compatibility drift
+- Planning framework/runtime upgrades
+
+## Workflow
+1. Inventory current vs target versions
+2. Classify risk
+3. Read changelog and migration notes
+4. Upgrade in small batches
+5. Validate each batch
+6. Record result + rollback readiness
+
+---
+
+## Risk Matrix
+
+| Factor | Low | Medium | High |
+|---|---|---|---|
+| Semver delta | patch | minor | major |
+| Package role | dev-only | runtime leaf | core/framework |
+| Usage depth | narrow | moderate | broad/systemic |
+| Coupling | isolated | shared utility | plugin/framework hub |
+| Migration effort | none | config tweaks | API/data/protocol changes |
+| Security urgency | none | moderate | critical/exploited |
+
+### Tier Rule
+- **Tier 1:** patch + low coupling
+- **Tier 2:** minor runtime or coupled package
+- **Tier 3:** major version or security-critical package
+
+---
+
+## Semver Impact Analysis
+
+### Patch (`x.y.Z`)
+- Usually low risk bugfix/perf updates
+- Batch multiple Tier 1 packages
+- Still run tests + lock checks
+
+### Minor (`x.Y.z`)
+- Can introduce deprecations
+- Upgrade in small related groups
+- Run integration checks for touched flows
+
+### Major (`X.y.z`)
+- Assume breakage until verified
+- Upgrade one package family at a time
+- Require migration checklist + rollback rehearsal
+
+## Inventory Commands
+```bash
+# Node
+npm outdated || true
+pnpm outdated || true
+yarn outdated || true
+
+# Security baseline
+npm audit --omit=dev || true
+pnpm audit || true
+yarn npm audit || true
+
+# Other ecosystems
+pip list --outdated || true
+cargo outdated || true
+go list -m -u all || true
+```
+
+Capture per package: current, target, semver delta, reason, affected subsystem.
+
+---
+
+## Upgrade Execution
+
+### Batch Sizing
+- Tier 1: up to 5 packages
+- Tier 2: 1–3 related packages
+- Tier 3: one package family at a time
+
+### Common Commands
+```bash
+npm install pkg@latest
+pnpm up pkg@latest
+yarn up pkg@latest
+
+pip install -U pkg
+cargo update -p crate_name
+go get module@latest
+```
+
+After each batch:
+1. Reinstall with lock constraints
+2. Run validation gates
+3. Run one runtime smoke path
+
+---
+
+## Lock File Management
+
+### Rules
+- Commit manifest and lockfile together
+- Never hand-edit lockfiles
+- Keep one package manager authoritative
+
+### Integrity Checks
+```bash
+npm ci
+pnpm install --frozen-lockfile
+yarn install --immutable
+```
+
+---
+
+## Security Audit Commands
+```bash
+npm audit --production
+pnpm audit
+yarn npm audit
+pip-audit
+cargo audit
+osv-scanner .
+```
+
+---
+
+## Validation Gates (Per Batch)
+```bash
+npm run lint
+npm run typecheck
+npm test
+```
+
+For services/APIs, also run startup check and one critical endpoint smoke test.
+
+---
+
+## Rollback Procedures
+
+### Fast Rollback
+```bash
+git checkout -- package.json package-lock.json pnpm-lock.yaml yarn.lock
+npm ci || pnpm install --frozen-lockfile || yarn install --immutable
+```
+
+### Commit Rollback
+```bash
+git revert <upgrade-commit-sha>
+# rerun validation gates
+```
+
+### Rollback Triggers
+- Critical tests fail with no fix in 30 minutes
+- Startup/runtime crash appears after upgrade
+- Security regression introduced
+- Production API/data contract breaks
+
+---
+
+## Common Pitfalls
+- Upgrading framework core before adapters/plugins
+- Ignoring peer dependency warnings
+- Mixing lockfiles from multiple package managers
+- Running only unit tests when integration behavior changed
+
+## Reporting Template
+```markdown
+## Upgrade Summary
+- Batch: N
+- Risk: tier 1/2/3
+- Packages: old -> new
+
+## Validation
+- lint/typecheck/tests/smoke: pass/fail
+
+## Security
+- audit before: ...
+- audit after: ...
+
+## Rollback
+- command prepared/tested: yes/no
+```
+
+## Exit Criteria
+- Every changed package has risk tier + rationale
+- Validation passes after each batch
+- Lockfile integrity checks pass
+- Rollback path is documented and executable

package/.codex/skills/design-system-audit/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: design-system-audit
+description: Unified design audit workflow for UI pattern analysis, design token auditing, and visual comparison against specs
+version: 2.0.0
+tags: [design, audit, ui]
+dependencies: []
+---
+
+# Design System Audit
+
+> **Replaces** separate, overlapping design review skills — unified design analysis covering UI patterns, design tokens, and visual properties
+
+Use this skill for end-to-end design analysis across code, screenshots, and design specs.
+
+## When to Use
+
+- Auditing UI consistency across a component library or app
+- Documenting existing patterns before refactor or migration
+- Extracting/validating design tokens from implementation and visuals
+- Comparing rendered output against mockups/Figma/screenshots
+
+## When NOT to Use
+
+- Pure backend work with no user-facing UI
+- One-off micro tweak where system-level consistency is irrelevant
+
+## Modes
+
+### UI Pattern Analysis
+Analyze component patterns, identify inconsistencies, document undocumented patterns.
+
+Focus areas:
+
+- Component variants and usage drift
+- Repeated interaction patterns (forms, tables, dialogs, navigation)
+- Pattern ownership (where canonical implementation should live)
+- Inconsistent states (hover/focus/disabled/error/loading)
+
+Deliverables:
+
+- Pattern inventory with file references
+- Consolidation candidates
+- Priority fixes by user impact
+
+### Design Token Audit
+Extract and verify color, typography, spacing tokens against implementation.
+
+Focus areas:
+
+- Color token usage vs one-off literals
+- Typography scale consistency (size/weight/line-height)
+- Spacing/radius/shadow value normalization
+- Semantic token gaps (text-muted, border-subtle, success, warning, etc.)
+
+Deliverables:
+
+- Token map (source of truth + current usage)
+- Drift report (where implementation diverges)
+- Proposed canonical token set and migration order
+
+### Visual Comparison
+Compare rendered output against mockups/specs with specific measurements.
+
+Focus areas:
+
+- Pixel-level spacing/sizing mismatches
+- Color differences (hex-level)
+- Typography mismatches (font, size, weight, line height)
+- Layout/responsive behavior across breakpoints
+
+Deliverables:
+
+- Spec-vs-implementation discrepancy list
+- Severity-ranked visual defects
+- Concrete fix list with measurable targets
+
+## Recommended Workflow
+
+1. **Scope**
+   - Identify target surfaces (pages/components/states/breakpoints)
+   - Gather artifacts (code paths, screenshots, mockups)
+
+2. **Inventory**
+   - Capture pattern and token inventory from code + visuals
+   - Note duplicates, drift, and undocumented conventions
+
+3. **Cross-Reference**
+   - Validate findings against design system tokens/components
+   - Distinguish intentional exceptions from accidental drift
+
+4. **Measure**
+   - Record measurable values for each issue:
+     - hex color
+     - px/rem size
+     - spacing/gap/padding values
+     - breakpoint-specific behavior
+
+5. **Report**
+   - Produce actionable findings with file:line and target value
+   - Group by severity and migration effort
+
+## Audit Output Template
+
+```markdown
+## Design Audit: [Scope]
+
+### Findings
+1. [Severity] [Issue]
+   - File: `path/to/file.tsx:123`
+   - Current: `#6B7280`, `14px`, `gap: 10px`
+   - Expected: `var(--color-text-muted)`, `13px`, `gap: 8px`
+   - Impact: [consistency/accessibility/brand mismatch]
+
+### Token Drift Summary
+- Colors: X one-offs, Y missing semantic mappings
+- Typography: X non-scale values
+- Spacing: X non-token values
+
+### Priority Actions
+- P0: [high impact, low effort]
+- P1: [high impact, medium effort]
+- P2: [design debt cleanup]
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Hurts | Better Approach |
+| --- | --- | --- |
+| Vague feedback ("looks good") instead of specific measurements | Not actionable, impossible to verify | Report concrete values (hex, px/rem, exact delta) |
+| Not checking existing design tokens before proposing new values | Creates token sprawl and inconsistency | Map to existing tokens first; add new tokens only when justified |
+| Auditing in isolation without cross-referencing the design system | Flags intentional patterns as bugs | Validate each finding against canonical component/token sources |
+| Reporting visual issues without checking responsive breakpoints | Misses major UX regressions on mobile/tablet | Verify each issue across defined breakpoints and states |
+
+## Verification
+
+After audit: every finding should reference a specific file:line and measurable value (hex color, px size, etc.)
+
+Minimum quality gate:
+
+- Each finding has location + current value + expected value
+- Each recommendation maps to token/system guidance
+- Responsive states checked for impacted components
+
+## Storage
+
+- Save audits to `.codex/memory/design/audits/`
+- Save extracted token snapshots to `.codex/memory/design/tokens/`
+
+## See Also
+
+- `mockup-to-code`
+- `frontend-design`
+- `accessibility-audit`