init claude

.claude/commands/retrospective.md

@@ -0,0 +1,81 @@
+---
+description: Analyze the current session and extract learnings to memory
+allowed-tools: Read, Edit, Grep, Bash, Task
+---
+
+# Session Retrospective
+
+Analyze this coding session and extract valuable learnings to improve future sessions.
+
+## Your Task
+
+### 1. Review What Happened This Session
+
+The session transcript is at: $CLAUDE_SESSION_TRANSCRIPT_PATH
+
+**Important**: Session transcripts can be large. Use these strategies:
+- Use `Read` with `offset` and `limit` parameters to read portions (e.g., last 500 lines)
+- Use `Grep` to search for specific patterns like "Error", "Edit", "Write" to find key moments
+- Use `Bash` with `tail` or `head` to get specific portions
+- Focus on the most recent activity (end of file) for the session summary
+
+Reflect on the session:
+- What code was written or modified?
+- What problems were solved?
+- What approaches were tried (both successful and unsuccessful)?
+- Were there any surprises or unexpected behaviors?
+
+### 2. Identify Learnings
+
+Extract insights in these categories:
+
+**Patterns (what worked well)**:
+- Successful approaches that should be reused
+- Code patterns that solved problems effectively
+- Workflows that were efficient
+
+**Failures (what to avoid)**:
+- Approaches that didn't work
+- Bugs that were encountered and their root causes
+- Time wasted on wrong paths
+- Assumptions that turned out to be wrong
+
+**Edge Cases**:
+- Tricky scenarios discovered
+- Non-obvious behavior found
+- Boundary conditions that matter
+
+**Technology Insights**:
+- Framework/library-specific knowledge gained
+- API quirks discovered
+- Performance considerations learned
+
+### 3. Update learnings.md
+
+Edit `.claude/skills/codebase-agent/learnings.md` and add new entries under the appropriate sections.
+
+Use this format for each entry:
+
+```markdown
+### [Short Descriptive Title]
+- **Context**: When does this apply?
+- **Learning**: What is the insight?
+- **Example**: (optional) Code snippet or concrete example
+- **Session**: [Date or brief session description]
+```
+
+### 4. Quality Guidelines
+
+Be selective about what to add:
+- **Add** genuinely useful, project-specific insights
+- **Skip** general programming knowledge (things any developer would know)
+- **Skip** one-time fixes that won't recur
+- **Avoid** duplicating existing entries
+- **Merge** with existing entries if they're related
+
+## Output
+
+Summarize:
+1. How many learnings were added (and to which categories)
+2. Brief description of the most important insights
+3. Any patterns emerging across sessions

.claude/commands/setup-agent.md

@@ -0,0 +1,73 @@
+---
+description: Analyze codebase and set up the learning agent (run once after install)
+allowed-tools: Read, Grep, Glob, Edit
+---
+
+# Initial Codebase Assessment
+
+You are setting up the continual learning agent for this codebase. This is a one-time setup that analyzes the project and configures the agent.
+
+## Your Task
+
+### 1. Analyze the Codebase Structure
+
+Explore the project to understand:
+- **Directory structure**: What are the key directories and their purposes?
+- **Tech stack**: What languages, frameworks, and libraries are used?
+- **Configuration files**: Find package.json, tsconfig.json, pyproject.toml, Cargo.toml, etc.
+- **Build tools**: How is the project built and tested?
+- **Entry points**: Where does the application start?
+
+### 2. Discover Conventions
+
+Look for patterns in the existing code:
+- **Code style**: Indentation, naming conventions, file organization
+- **Architectural patterns**: MVC, component-based, microservices, etc.
+- **Testing patterns**: How are tests structured? What testing frameworks?
+- **Documentation patterns**: How is code documented?
+
+### 3. Update the Skill File
+
+Edit `.claude/skills/codebase-agent/SKILL.md` and replace the `## Codebase Context` section with your findings:
+
+```markdown
+## Codebase Context
+
+### Architecture
+[Brief overview of the architecture]
+
+### Tech Stack
+- **Language(s)**: [e.g., TypeScript, Python]
+- **Framework(s)**: [e.g., React, FastAPI]
+- **Key Libraries**: [important dependencies]
+
+### Key Directories
+- `src/` - [purpose]
+- `tests/` - [purpose]
+- [etc.]
+
+### Build & Test Commands
+- Build: `[command]`
+- Test: `[command]`
+- Lint: `[command]`
+
+### Conventions
+- [Convention 1]
+- [Convention 2]
+```
+
+### 4. Initialize Learnings
+
+Edit `.claude/skills/codebase-agent/learnings.md` and add any initial observations:
+- Obvious patterns you notice in the code
+- Potential edge cases visible in the structure
+- Tech stack insights that would be helpful to remember
+
+## Output
+
+After completing the assessment:
+1. Summarize what you learned about the codebase
+2. Confirm the skill file has been updated
+3. Note any initial learnings added
+
+The agent is now ready for coding. Future sessions will automatically accumulate more learnings!

.claude/hooks/session-end.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# SessionEnd Hook - Triggers learning extraction
+#
+# This hook runs automatically after each Claude Code session.
+# It spawns a background process to analyze the session and update learnings.
+#
+
+LOG_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/session-end.log"
+
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
+}
+
+# Read hook input from stdin (JSON with session info)
+INPUT=$(cat)
+
+log "Hook triggered with input: $INPUT"
+
+# Extract transcript path using jq (required dependency)
+if ! command -v jq &> /dev/null; then
+    log "ERROR: jq not available"
+    exit 0
+fi
+
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+log "Transcript: $TRANSCRIPT"
+log "Session ID: $SESSION_ID"
+log "Project dir: $PROJECT_DIR"
+
+# Prevent duplicate triggers for the same session using a lock file
+LOCK_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/locks"
+mkdir -p "$LOCK_DIR"
+LOCK_FILE="$LOCK_DIR/$SESSION_ID.lock"
+
+if [ -f "$LOCK_FILE" ]; then
+    log "Session already processed (lock exists) - skipping duplicate trigger"
+    exit 0
+fi
+
+# Create lock file immediately
+echo "$(date)" > "$LOCK_FILE"
+log "Lock file created"
+
+# Clean up old lock files (older than 1 hour)
+find "$LOCK_DIR" -name "*.lock" -mmin +60 -delete 2>/dev/null
+
+# Validate transcript exists
+if [ -z "$TRANSCRIPT" ]; then
+    log "ERROR: No transcript path in input"
+    exit 0
+fi
+
+if [ ! -f "$TRANSCRIPT" ]; then
+    log "ERROR: Transcript file does not exist: $TRANSCRIPT"
+    exit 0
+fi
+
+# Only run retrospective if session was substantial (more than 10 lines)
+LINE_COUNT=$(wc -l < "$TRANSCRIPT" 2>/dev/null || echo "0")
+log "Transcript line count: $LINE_COUNT"
+if [ "$LINE_COUNT" -lt 10 ]; then
+    log "Session too short, skipping retrospective"
+    exit 0
+fi
+
+# CRITICAL: Detect if this session was itself a retrospective to prevent chain reaction
+# Check if the transcript contains /retrospective command (indicates this was a retrospective session)
+if grep -q '"/retrospective' "$TRANSCRIPT" 2>/dev/null || grep -q '"skill":"retrospective"' "$TRANSCRIPT" 2>/dev/null; then
+    log "Session was a retrospective - skipping to prevent chain reaction"
+    exit 0
+fi
+
+# Check if learnings.md exists (system is properly set up)
+LEARNINGS_FILE="$PROJECT_DIR/.claude/skills/codebase-agent/learnings.md"
+if [ ! -f "$LEARNINGS_FILE" ]; then
+    log "ERROR: learnings.md not found at $LEARNINGS_FILE"
+    exit 0
+fi
+
+log "Starting retrospective analysis in background..."
+
+# Run retrospective in background using the /retrospective slash command
+# Pass transcript path as argument so the command knows where to read the session
+# Use nohup to ensure the process survives after hook exits
+(
+    cd "$PROJECT_DIR" && nohup claude --dangerously-skip-permissions \
+        -p "/retrospective
+
+The session transcript is at: $TRANSCRIPT
+Read it to understand what happened in this session." \
+        >> "$LOG_FILE" 2>&1 &
+) &
+
+log "Background process spawned"
+
+# Exit immediately - don't wait for background process
+exit 0

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh\"",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/codebase-agent/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: codebase-agent
+description: |
+  Expert coding agent for this codebase. Learns from every session to improve
+  code quality, catch edge cases, and apply proven patterns. Use for ANY coding
+  task: writing, debugging, refactoring, testing. Accumulates project knowledge.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Codebase Expert Agent
+
+You are an expert coding agent that learns and improves over time.
+
+## Accumulated Learnings
+
+Reference [learnings.md](learnings.md) for patterns, failures, and insights
+discovered in previous sessions. Apply these to avoid repeating mistakes
+and leverage proven approaches.
+
+## Behavior
+
+1. **Check learnings first**: Before implementing, scan learnings.md for relevant patterns and failures
+2. **Apply proven patterns**: Use approaches that worked in past sessions
+3. **Follow conventions**: Adhere to project conventions discovered in learnings
+4. **Note discoveries**: When you find something new (pattern, failure, edge case), mention it
+
+## Code Simplicity
+
+**Default to the simplest solution that works.** Resist the urge to over-engineer.
+
+### Write Less Code
+
+- Solve the actual problem, not hypothetical future problems
+- If a function is called once, consider inlining it
+- Three similar lines are better than a premature abstraction
+- Use standard library and built-ins before writing custom code
+- Delete code paths that can't happen
+
+### Keep It Flat
+
+- Use early returns and guard clauses to reduce nesting
+- Avoid callback pyramids - flatten with async/await or composition
+- One level of abstraction per function
+
+### Avoid Premature Abstraction
+
+- Don't add parameters "in case we need them later"
+- Don't create base classes until you have 2+ implementations
+- Don't add config for things that could be hardcoded
+- Don't create wrapper functions that just call another function
+
+### Trust Your Code
+
+- Don't defensively code against impossible internal states
+- Don't catch errors you can't meaningfully handle
+- Don't validate data that's already validated upstream
+- Validate at system boundaries (user input, external APIs), trust internal code
+
+### When in Doubt
+
+Ask: "What's the least code that makes this work?" Write that first. Add complexity only when reality demands it.
+
+## Codebase Context
+
+<!-- POPULATED BY /setup-agent -->
+<!-- Run /setup-agent after installation to populate this section -->
+<!-- Architecture, tech stack, key directories, and conventions will be added here -->

.claude/skills/codebase-agent/learnings.md

@@ -0,0 +1,44 @@
+# Accumulated Learnings
+
+This file is automatically updated after each coding session.
+The SessionEnd hook triggers `/retrospective` which analyzes the session and adds new learnings here.
+
+---
+
+## Patterns (What Works)
+
+Successful approaches and code patterns that should be reused.
+
+<!-- Patterns will be added by /retrospective -->
+
+---
+
+## Failures (What to Avoid)
+
+Approaches that failed, bugs encountered, and time-wasting paths.
+
+<!-- Failures will be added by /retrospective -->
+
+---
+
+## Edge Cases
+
+Tricky scenarios and non-obvious behaviors discovered during development.
+
+<!-- Edge cases will be added by /retrospective -->
+
+---
+
+## Technology Insights
+
+Framework-specific knowledge, library quirks, and API insights.
+
+<!-- Technology insights will be added by /retrospective -->
+
+---
+
+## Conventions
+
+Project-specific coding conventions and style guidelines.
+
+<!-- Conventions will be added by /setup-agent and /retrospective -->