codexkit 1.0.0

package/.codex/skills/react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/.codex/skills/react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/.codex/skills/react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/.codex/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+version: 1.0.0
+tags: [workflow, code-quality]
+dependencies: []
+---
+
+# Code Review Reception
+
+> **Replaces** blind agreement with reviewer suggestions — requires technical verification and understanding before implementing any feedback
+
+## When to Use
+
+- You received review feedback and need to evaluate it before implementing
+- Feedback seems unclear, questionable, or potentially wrong for this codebase
+
+## When NOT to Use
+
+- You already verified and accepted the feedback and are ready to implement
+- You need to request a review (use requesting-code-review)
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Review Intake Checklist
+
+- [ ] Read the full feedback without reacting
+- [ ] Restate requirements in your own words
+- [ ] Verify against codebase reality
+- [ ] Evaluate technical correctness for this stack
+- [ ] Respond with acknowledgment or reasoned pushback
+- [ ] Implement one item at a time with tests
+
+## Forbidden Responses
+
+**NEVER:**
+
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake                      | Fix                                 |
+| ---------------------------- | ----------------------------------- |
+| Performative agreement       | State requirement or just act       |
+| Blind implementation         | Verify against codebase first       |
+| Batch without testing        | One at a time, test each            |
+| Assuming reviewer is right   | Check if breaks things              |
+| Avoiding pushback            | Technical correctness > comfort     |
+| Partial implementation       | Clarify all items first             |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.
+
+## See Also
+
+- **requesting-code-review** — the complementary skill for dispatching reviews
+- **verification-before-completion** — verification after implementing review feedback
+- **systematic-debugging** — when review feedback reveals a deeper issue

package/.codex/skills/refactoring/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: refactoring
+description: Test-backed refactoring playbook for safe structural improvements without behavior changes.
+---
+
+# refactoring
+
+## Purpose
+Improve code structure while preserving externally observable behavior.
+
+## Use This Skill When
+- Reducing duplication that causes divergent bugs
+- Improving naming and module boundaries
+- Splitting oversized files/functions for maintainability
+- Removing brittle conditionals and hidden coupling
+
+## Workflow Phases
+1. Baseline
+2. Transform
+3. Stabilize
+4. Verify
+
+## Expected Outputs
+- Clearer structure with unchanged behavior
+- Passing tests before and after
+- Focused structural diff (not feature work)
+- Brief note of moved/renamed symbols
+
+## Success Indicators
+- No externally visible behavior changes
+- Smaller units and lower branch complexity
+- Cleaner dependency direction
+- Reviewable, incremental commits
+
+## Fast Start
+```bash
+npm test
+npm run typecheck
+npm run lint
+git diff --stat
+```
+
+## Pre-Refactor Requirements
+- Existing tests cover touched behavior.
+- Baseline is green before first structural edit.
+- No mixed feature work in same refactor batch.
+
+## Core Techniques
+- Extract Method
+- Inline Method
+- Rename Symbol
+- Move Function/Class
+- Split File/Module
+- Introduce Parameter Object
+
+## Safety Nets (Mandatory)
+- Add characterization tests when behavior is unclear.
+- Refactor in micro-steps with runnable checkpoints.
+- Re-run tests after each non-trivial transformation.
+- Keep public interfaces stable unless change is explicitly approved.
+- Preserve logging, metrics labels, and error shapes at boundaries.
+
+## Technique Selection Matrix
+| Symptom | Best Technique |
+|---|---|
+| Repeated logic blocks | Extract Method |
+| Misleading names | Rename Symbol |
+| Overgrown file | Split File |
+| Tight coupling across modules | Move Function/Class |
+| Too many parameters | Introduce Parameter Object |
+
+## Refactoring Recipes
+
+### 1) Extract Function
+**Use when:** one function does multiple jobs or repeats logic.
+
+Steps:
+1. Select a cohesive block with clear inputs/outputs.
+2. Create a function named for business intent.
+3. Pass dependencies explicitly.
+4. Replace block with call.
+5. Run focused tests.
+
+Checks:
+- No new side effects.
+- Function can be tested in isolation.
+
+### 2) Inline Function
+**Use when:** indirection hurts readability and function adds no semantic value.
+
+Steps:
+1. Confirm call sites are few and safe to edit.
+2. Replace call with implementation while preserving evaluation order.
+3. Remove dead function.
+4. Run tests + typecheck.
+
+Checks:
+- No duplicated complex logic introduced.
+- No repeated expensive operations added.
+
+### 3) Rename Symbol
+**Use when:** naming no longer matches behavior.
+
+Steps:
+1. Choose domain language, not implementation details.
+2. Use symbol-aware rename tools.
+3. Update docs/tests/comments in same change.
+4. Keep backwards aliases only when required.
+
+Checks:
+- No shadowing conflicts.
+- Telemetry/search queries remain traceable.
+
+### 4) Move Function/Class
+**Use when:** logic is far from the data or policy it belongs to.
+
+Steps:
+1. Identify ownership boundary.
+2. Move symbol and update callers.
+3. Add temporary shim only if migration is staged.
+4. Remove shim once migration completes.
+
+Checks:
+- No circular imports.
+- Dependency direction improves.
+
+### 5) Split Module
+**Use when:** file has unrelated concerns and high cognitive load.
+
+Steps:
+1. Group exports by capability.
+2. Create focused modules with explicit public API.
+3. Move code in slices and verify after each slice.
+4. Remove dead exports.
+
+Checks:
+- Each module has one reason to change.
+- Avoid pass-through wrapper files.
+
+### 6) Introduce Parameter Object
+**Use when:** multiple call sites pass 4+ related params.
+
+Steps:
+1. Define typed object with required/optional fields.
+2. Migrate call sites incrementally.
+3. Centralize defaults/validation.
+4. Remove legacy signature.
+
+Checks:
+- Object represents one domain concept.
+- No unrelated fields bundled together.
+
+## Additional Practical Patterns
+
+### Replace Conditional with Dispatch Table
+Use a map of handlers keyed by type/state to reduce deep `if/else` trees.
+- Keep fallback handler explicit.
+- Add test for unknown key path.
+
+### Introduce Guard Clauses
+Flatten nested conditionals with early returns.
+- Keep failure reasons explicit.
+- Preserve exact error codes/messages.
+
+### Decompose Long Pipeline
+Break long transformation chains into named stages.
+- Stage names should reflect business steps.
+- Validate intermediate invariants in tests.
+
+## High-Risk Areas During Refactor
+- Time zones, date arithmetic, money calculations.
+- Transaction boundaries and retry/idempotency semantics.
+- Concurrency primitives (locks, channels, async cancellation).
+- Serialization formats consumed by external clients.
+- Error translation layers and retry backoff logic.
+
+## When NOT to Refactor
+- Active incident or hotfix window.
+- No safety tests and no time to add characterization tests.
+- Ongoing architecture decision that may invalidate structure choices.
+- PR already contains major behavioral changes.
+- Release freeze without reviewer capacity.
+
+## Verification Strategy
+- Unit tests for extracted pure logic.
+- Integration tests for unchanged contracts.
+- Snapshot/API comparison where response shape matters.
+- Performance smoke tests for known hot paths.
+
+## Refactor Change Log Template
+```markdown
+## Refactor Scope
+- Modules:
+- Techniques used:
+
+## Guardrails
+- Baseline tests:
+- Characterization tests added:
+
+## Outcomes
+- Duplication reduced:
+- Boundary improvements:
+- Deferred follow-ups:
+```
+
+## Common Failure Modes
+- Hidden behavior changes labeled as cleanup.
+- One giant refactor commit that is hard to review.
+- Symbol renames without updating tests/docs.
+- Moving code and creating cyclic dependencies.
+- Deleting dynamically referenced code as “unused”.
+
+## Exit Criteria
+- Baseline and post-refactor tests pass.
+- Behavior is unchanged at public boundaries.
+- Diff is structural, incremental, and reviewer-comprehensible.
+- Any deferred cleanup is documented as follow-up work.