Claude Development Framework

# Claude Development Framework

**Make Claude a better work partner through context persistence and pattern enforcement.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.4.0-brightgreen.svg)](CHANGELOG.md)

---

## What Is This?

A framework that makes Claude Code:

1. **Remember across sessions** - Context persists. What Claude learns today carries forward.
2. **Work your way** - Your preferences, patterns, and voice are enforced consistently.
3. **Improve over time** - Feedback loop captures data, detects issues, reflects on what to change.

Without this, every Claude session starts blank. With it, Claude has history, learnings, and awareness.

### How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                    SESSION LIFECYCLE                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  SessionStart → Loads identity, task, learnings from brain  │
│       ↓                                                      │
│  During Session → Hooks track everything (tools, files,     │
│                   commands, failures)                        │
│       ↓                                                      │
│  /checkpoint or PreCompact → Saves state to brain           │
│       ↓                                                      │
│  SessionEnd → Writes summary for next session               │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### The Feedback Loop

```
CAPTURE ──► DETECT ──► DECIDE ──► ACT
   │           │          │        │
   │           │          │        └─► Write to brain files
   │           │          │
   │           │          └─► /reflect analyzes, suggests changes
   │           │
   │           └─► awareness.js notices issues (large files,
   │               failures, long sessions)
   │
   └─► Tracking hooks log everything
```

### Two Layers

**Global Layer** (Antigravity - `~/.gemini/antigravity/`):
- Brain storage for persistent context (learnings, patterns, decisions)
- SessionStart/PreCompact scripts that load and save state
- Shared with Gemini for cross-agent context

**Framework Layer** (this repo - copied to projects via `/update-framework`):
- Slash commands for workflows
- Hooks for safety, tracking, context injection
- Specs for pattern enforcement

Works with any stack: React, Vue, Svelte, Next.js, Python, Rust, Go, etc.

---

## Quick Start

```bash
# 1. Fork this repo, then clone your fork
git clone https://github.com/YOUR-USERNAME/claude-dev-framework.git

# 2. Copy .claude/ to your project
cp -r claude-dev-framework/.claude your-project/.claude

# 3. In your project, run
/sync-stack
```

That's it. Claude now follows your patterns.

---

## When to Use What

### Starting a New Project

```
/sync-stack              # Detects stack, generates specs
/start-task              # Build something
```

### Adding to an Existing Project

```
/sync-stack              # Reads your code, learns your patterns
/start-task              # Build following those patterns
```

### Planning a Complex Feature

```
/add-feature             # Creates PRD + task breakdown
/process-tasks           # Executes tasks one by one
```

### Adding a New Dependency

```
/sync-stack prisma       # Generate specs for just that dependency
```

### Committing and PRs

```
/commit                  # Commit with proper message format
/pr                      # Create pull request
```

### Checking Code Quality

```
/verify                  # Check code against your specs
/audit                   # Deep parallel review (security, performance, tests)
```

### Understanding Code

```
/learn                   # Explain anything in plain English
/learn react hooks       # Explain a specific topic
```

### Managing Context

```
/checkpoint              # Save session context before ending work
/reflect                 # Analyze patterns, identify improvements
```

---

## Commands

Descriptions match command frontmatter (source of truth in `.claude/commands/`).

### Development

| Command | Description |
|---------|-------------|
| `/start-task` | Start any coding task. Loads stack config and specs, gathers requirements interactively, then executes. |
| `/add-feature` | Plan a complex feature before building. Creates PRD, breaks into tasks. Use when feature needs multiple components or design decisions. |
| `/process-tasks` | Execute a task list one at a time. Use after /add-feature to implement each subtask with verification and commits. |
| `/commit` | Commit changes using project specs. Loads version-control.md, updates docs to reflect changes, then commits. |
| `/pr` | Create a pull request. Checks branch status, generates summary from commits, creates PR with gh cli. |

### Project Setup

| Command | D

... (truncated)