add claude settings

Author: meganrm

.claude/settings.json

@@ -0,0 +1,79 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(git worktree:*)",
+      "Bash(git show:*)",
+      "Bash(git stash:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git checkout:*)",
+      "Bash(git switch:*)",
+      "Bash(git merge:*)",
+      "Bash(git rebase:*)",
+      "Bash(git blame:*)",
+      "Bash(git remote:*)",
+      "Bash(git fetch:*)",
+      "Bash(git tag:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(wc:*)",
+      "Bash(sort:*)",
+      "Bash(uniq:*)",
+      "Bash(cut:*)",
+      "Bash(tr:*)",
+      "Bash(diff:*)",
+      "Bash(file:*)",
+      "Bash(stat:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(touch:*)",
+      "Bash(echo:*)",
+      "Bash(pwd:*)",
+      "Bash(which:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(rg:*)",
+      "Bash(fd:*)",
+      "Bash(tree:*)",
+      "Bash(du:*)",
+      "Bash(env:*)",
+      "Bash(printenv:*)",
+      "Bash(date:*)",
+      "Bash(jq:*)",
+      "Bash(sed:*)",
+      "Bash(awk:*)",
+      "Bash(xargs:*)",
+      "Bash(tee:*)",
+      "Bash(basename:*)",
+      "Bash(dirname:*)",
+      "Bash(gh:*)",
+      "Bash(node:*)",
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(bun:*)",
+      "Bash(bunx:*)",
+      "Bash(afplay:*)",
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Agent"
+    ],
+    "deny": [
+      "Bash(rm -rf /:*)",
+      "Bash(rm -rf ~:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git clean -f:*)",
+      "Bash(git branch -D:*)"
+    ]
+  }
+}

.claude/skills/code-review/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: code-review
+description: Review a PR or set of changes for code quality, correctness, and team standards. Use when user wants a code review, PR review, asks to review changes, or mentions "review this".
+---
+
+# Code Review
+
+Perform a thorough code review on a PR or set of changes, producing actionable feedback organized by severity.
+
+## Process
+
+### 1. Gather the changes
+
+Determine what to review:
+- If given a PR number/URL: `gh pr diff <number>` and `gh pr view <number>`
+- If reviewing local changes: `git diff` or `git diff <branch>`
+- If given specific files: read those files
+
+Also read the PR description or task file for context on intent.
+
+### 2. Understand the context
+
+Before reviewing line-by-line:
+- What problem is this solving? (read PR description, linked issues, task files)
+- What are the acceptance criteria?
+- Which files are test files vs production code?
+
+### 3. Review systematically
+
+Check each area in order of importance:
+
+#### Correctness
+- Does the code do what the PR/task says it should?
+- Are there logic errors, off-by-ones, missing edge cases?
+- Are error conditions handled?
+- Could this break existing functionality?
+
+#### Security
+- Any user input used without validation/sanitization?
+- Secrets or credentials exposed?
+- SQL injection, XSS, command injection risks?
+- Overly permissive access controls?
+
+#### Scope compliance
+- Does the change stay within the stated goal?
+- Any "while I'm here" changes that should be separate?
+- Speculative features or premature abstractions?
+
+#### Redundancy & reuse
+- Does new code duplicate existing utilities?
+- Could existing helpers be used instead?
+- Are there repeated patterns that should be extracted?
+
+#### Type safety & API design
+- Are public interfaces well-typed?
+- Are function signatures clear about what they accept and return?
+- Any `any` types without justification?
+
+#### Test quality
+- Do tests verify behavior through public interfaces?
+- Are tests coupled to implementation details?
+- Are critical paths covered?
+- Do tests read like specifications?
+
+#### Style & consistency
+- Does the code follow the patterns established in this repo?
+- Naming conventions followed?
+- File organization consistent with project structure?
+
+### 4. Present findings
+
+Organize feedback into three categories:
+
+**Must fix** — Issues that should block merge:
+- Bugs, security issues, correctness problems
+- Breaking changes without migration
+- Missing tests for critical paths
+
+**Should fix** — Issues worth addressing but not blocking:
+- Minor redundancy or missed reuse opportunities
+- Style inconsistencies
+- Weak typing that could be stronger
+
+**Nit** — Optional improvements:
+- Naming suggestions
+- Minor readability improvements
+- Alternative approaches to consider
+
+For each finding:
+- Reference the specific file and line(s)
+- Explain *why* it's an issue (not just *what* to change)
+- Suggest a concrete fix when possible
+
+### 5. Summary
+
+End with:
+- Overall assessment (approve, request changes, or needs discussion)
+- What the PR does well (acknowledge good work)
+- The most important 1-2 items to address
+
+## Adapting for team use
+
+When used as part of a team code review workflow:
+- Check the repo's `CLAUDE.md` for project-specific standards
+- Reference team conventions when flagging issues
+- Distinguish between objective issues (bugs) and subjective preferences (style)
+- Be explicit about which standards come from the project vs general best practices

.claude/skills/grill-me/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

.claude/skills/improve-codebase-architecture/REFERENCE.md

@@ -0,0 +1,65 @@
+# Reference
+
+## Dependency Categories
+
+When assessing a candidate for deepening, classify its dependencies:
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary. Define a port (interface) at the module boundary. Tests use an in-memory adapter. Production uses the real adapter.
+
+### 4. True external (Mock)
+
+Third-party services you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port.
+
+## Testing Strategy
+
+**Replace, don't layer.**
+
+- Old unit tests on shallow modules are waste once boundary tests exist — delete them
+- Write new tests at the deepened module's interface boundary
+- Tests assert on observable outcomes through the public interface
+- Tests should survive internal refactors
+
+## Issue Template
+
+<issue-template>
+
+## Problem
+
+- Which modules are shallow and tightly coupled
+- What integration risk exists in the seams between them
+- Why this makes the codebase harder to navigate and maintain
+
+## Proposed Interface
+
+- Interface signature (types, methods, params)
+- Usage example showing how callers use it
+- What complexity it hides internally
+
+## Dependency Strategy
+
+Which category applies and how dependencies are handled.
+
+## Testing Strategy
+
+- **New boundary tests to write**: behaviors to verify at the interface
+- **Old tests to delete**: shallow module tests that become redundant
+- **Test environment needs**: local stand-ins or adapters required
+
+## Implementation Recommendations
+
+- What the module should own (responsibilities)
+- What it should hide (implementation details)
+- What it should expose (the interface contract)
+- How callers should migrate to the new interface
+
+</issue-template>

.claude/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: improve-codebase-architecture
+description: Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
+---
+
+# Improve Codebase Architecture
+
+Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as GitHub issue RFCs.
+
+A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
+
+## Process
+
+### 1. Explore the codebase
+
+Use the Agent tool with subagent_type=Explore to navigate the codebase naturally. Do NOT follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small files?
+- Where are modules so shallow that the interface is nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
+- Where do tightly-coupled modules create integration risk in the seams between them?
+- Which parts of the codebase are untested, or hard to test?
+
+The friction you encounter IS the signal.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate, show:
+
+- **Cluster**: Which modules/concepts are involved
+- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept
+- **Dependency category**: See [REFERENCE.md](REFERENCE.md) for the four categories
+- **Test impact**: What existing tests would be replaced by boundary tests
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. User picks a candidate
+
+### 4. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would need to rely on
+- A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints
+
+Show this to the user, then immediately proceed to Step 5.
+
+### 5. Design multiple interfaces
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1-3 entry points max"
+- Agent 2: "Maximize flexibility — support many use cases and extension"
+- Agent 3: "Optimize for the most common caller — make the default case trivial"
+- Agent 4 (if applicable): "Design around the ports & adapters pattern for cross-boundary dependencies"
+
+Each sub-agent outputs:
+
+1. Interface signature (types, methods, params)
+2. Usage example showing how callers use it
+3. What complexity it hides internally
+4. Dependency strategy (how deps are handled — see [REFERENCE.md](REFERENCE.md))
+5. Trade-offs
+
+Present designs sequentially, then compare them in prose. Give your own recommendation.
+
+### 6. User picks an interface (or accepts recommendation)
+
+### 7. Create GitHub issue
+
+Create a refactor RFC as a GitHub issue using `gh issue create`. Use the template in [REFERENCE.md](REFERENCE.md).