continual learning setup

README.md

@@ -0,0 +1,159 @@
+# Continual Learning System for Claude Code
+
+A self-improving coding agent that learns from every session. Patterns, failures, edge cases, and insights are automatically extracted and stored, making the agent smarter over time.
+
+## How It Works
+
+```
+Session 1: You code with Claude
+    |
+    v
+SessionEnd Hook fires
+    |
+    v
+/retrospective extracts learnings
+    |
+    v
+learnings.md is updated
+    |
+    v
+Session 2: Agent applies learnings from Session 1
+    |
+    v
+(repeat - agent gets smarter each session)
+```
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# Clone this repo
+git clone https://github.com/YOUR_ORG/continual-learning.git
+cd continual-learning
+
+# Install to your project
+./install.sh /path/to/your/project
+```
+
+### 2. Set Up the Agent
+
+```bash
+cd /path/to/your/project
+claude
+
+# In Claude Code, run:
+> /setup-agent
+```
+
+This analyzes your codebase and configures the agent with project-specific context.
+
+### 3. Start Coding
+
+Just work normally with Claude Code. After each session:
+- The `SessionEnd` hook automatically runs
+- `/retrospective` analyzes what happened
+- New learnings are added to `learnings.md`
+- Next session benefits from accumulated knowledge
+
+## What Gets Installed
+
+```
+your-project/
++-- .claude/
+    +-- skills/
+    |   +-- codebase-agent/
+    |       +-- SKILL.md        # Main agent skill
+    |       +-- learnings.md    # Accumulated learnings (grows over time)
+    |
+    +-- commands/
+    |   +-- setup-agent.md      # /setup-agent - Initial setup
+    |   +-- retrospective.md    # /retrospective - Extract learnings
+    |
+    +-- hooks/
+    |   +-- session-end.sh      # Auto-triggers after sessions
+    |
+    +-- settings.json           # Hook configuration
+```
+
+## Manual Commands
+
+While learning happens automatically, you can also trigger it manually:
+
+- `/setup-agent` - Re-analyze codebase and update skill context
+- `/retrospective` - Manually run learning extraction
+
+## Customization
+
+### Adjust the Skill
+
+Edit `.claude/skills/codebase-agent/SKILL.md` to:
+- Add project-specific instructions
+- Modify the agent's behavior
+- Include additional context
+
+### Adjust Learning Extraction
+
+Edit `.claude/commands/retrospective.md` to:
+- Change what categories of learnings to extract
+- Modify the format of learnings
+- Adjust selectivity (what gets saved vs skipped)
+
+### Disable Automatic Learning
+
+Remove the hook from `.claude/settings.json` to disable automatic learning.
+You can still run `/retrospective` manually when you want.
+
+## Requirements
+
+- Claude Code (latest version)
+- `jq` command-line tool (for parsing JSON in hooks)
+
+Install jq if needed:
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+apt-get install jq
+```
+
+## How Learnings Are Structured
+
+Learnings in `learnings.md` are organized into categories:
+
+- **Patterns**: Successful approaches to reuse
+- **Failures**: Mistakes to avoid
+- **Edge Cases**: Tricky scenarios to remember
+- **Technology Insights**: Framework/library-specific knowledge
+- **Conventions**: Project coding conventions
+
+Each learning follows this format:
+
+```markdown
+### [Short Title]
+- **Context**: When this applies
+- **Learning**: The insight
+- **Example**: Code snippet (optional)
+```
+
+## Philosophy
+
+This system is based on the idea that:
+
+1. **Agents should learn** - Not just follow static instructions
+2. **Every session has insights** - Patterns, failures, edge cases
+3. **Compounding knowledge** - Each session builds on previous ones
+4. **Human-readable memory** - Learnings are plain markdown, easy to review/edit
+5. **Shareable knowledge** - Commit learnings.md to git for team benefit
+
+## Contributing
+
+1. Fork the repo
+2. Make changes
+3. Test by installing to a real project
+4. Submit a PR
+
+## License
+
+MIT

commands/retrospective.md

@@ -0,0 +1,73 @@
+---
+description: Analyze the current session and extract learnings to memory
+allowed-tools: Read, Edit
+---
+
+# Session Retrospective
+
+Analyze this coding session and extract valuable learnings to improve future sessions.
+
+## Your Task
+
+### 1. Review What Happened This Session
+
+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

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!

hooks/session-end.sh

@@ -0,0 +1,47 @@
+#!/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.
+#
+
+# Read hook input from stdin (JSON with session info)
+INPUT=$(cat)
+
+# Extract transcript path using jq (required dependency)
+if ! command -v jq &> /dev/null; then
+    # jq not available, skip silently
+    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:-.}"
+
+# Validate transcript exists
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+    exit 0
+fi
+
+# Only run retrospective if session was substantial (more than 10 lines)
+LINE_COUNT=$(wc -l < "$TRANSCRIPT" 2>/dev/null || echo "0")
+if [ "$LINE_COUNT" -lt 10 ]; then
+    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
+    exit 0
+fi
+
+# Run retrospective in background using claude -p
+# This uses Claude Code's existing authentication
+(
+    claude -p "Run /retrospective to analyze the session and extract learnings. The session transcript is at: $TRANSCRIPT" \
+        --cwd "$PROJECT_DIR" \
+        2>/dev/null
+) &
+
+# Exit immediately - don't wait for background process
+exit 0

install.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+# Continual Learning System Installer
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/YOUR_ORG/continual-learning/main/install.sh | bash
+#   or: ./install.sh [target-dir]
+#
+# This installer:
+#   1. Copies skills, commands, and hooks to your project's .claude/ directory
+#   2. Configures the SessionEnd hook
+#   3. Prompts you to run /setup-agent to initialize the agent
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Determine target directory
+TARGET_DIR="${1:-.}"
+TARGET_DIR=$(cd "$TARGET_DIR" && pwd)
+
+# Determine script location (for local installs)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo -e "${GREEN}Continual Learning System Installer${NC}"
+echo "Installing to: $TARGET_DIR"
+echo ""
+
+# Check if .claude directory exists
+if [ -d "$TARGET_DIR/.claude" ]; then
+    echo -e "${YELLOW}Warning: .claude directory already exists${NC}"
+    read -p "Continue and merge files? (y/n) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Aborted."
+        exit 1
+    fi
+fi
+
+# Create directory structure
+echo "Creating directory structure..."
+mkdir -p "$TARGET_DIR/.claude/skills/codebase-agent"
+mkdir -p "$TARGET_DIR/.claude/commands"
+mkdir -p "$TARGET_DIR/.claude/hooks"
+
+# Copy files
+echo "Copying files..."
+
+# Function to copy file from local or download from remote
+copy_file() {
+    local src="$1"
+    local dest="$2"
+
+    if [ -f "$SCRIPT_DIR/$src" ]; then
+        # Local install
+        cp "$SCRIPT_DIR/$src" "$dest"
+    else
+        # Remote install - would need to update with actual repo URL
+        echo -e "${RED}Error: Source file not found: $src${NC}"
+        echo "For remote installation, update REPO_URL in this script."
+        exit 1
+    fi
+}
+
+copy_file "skills/codebase-agent/SKILL.md" "$TARGET_DIR/.claude/skills/codebase-agent/SKILL.md"
+copy_file "skills/codebase-agent/learnings.md" "$TARGET_DIR/.claude/skills/codebase-agent/learnings.md"
+copy_file "commands/setup-agent.md" "$TARGET_DIR/.claude/commands/setup-agent.md"
+copy_file "commands/retrospective.md" "$TARGET_DIR/.claude/commands/retrospective.md"
+copy_file "hooks/session-end.sh" "$TARGET_DIR/.claude/hooks/session-end.sh"
+
+# Make hook executable
+chmod +x "$TARGET_DIR/.claude/hooks/session-end.sh"
+
+# Handle settings.json merge
+echo "Configuring hooks..."
+SETTINGS_FILE="$TARGET_DIR/.claude/settings.json"
+
+if [ -f "$SETTINGS_FILE" ]; then
+    # Merge with existing settings
+    echo -e "${YELLOW}Existing settings.json found. Please manually add the hook configuration:${NC}"
+    echo ""
+    cat << 'EOF'
+Add to your .claude/settings.json:
+
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh\"",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+    echo ""
+else
+    # Create new settings.json
+    cat > "$SETTINGS_FILE" << 'EOF'
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh\"",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+fi
+
+echo ""
+echo -e "${GREEN}Installation complete!${NC}"
+echo ""
+echo "Next steps:"
+echo "  1. cd $TARGET_DIR"
+echo "  2. Run: claude"
+echo "  3. Type: /setup-agent"
+echo ""
+echo "This will analyze your codebase and set up the learning agent."
+echo "After that, the agent will automatically learn from each session!"

settings.json

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

skills/codebase-agent/SKILL.md

@@ -0,0 +1,31 @@
+---
+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
+
+## 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 -->

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 -->