claude-capsule-kit / templates

# Capsule Kit v3.0

Context memory for Claude Code. Capsule (SQLite) stores session state automatically via JS hooks. No manual logging needed.

## Requirements

- **Git**: Required for session tracking
- **Node.js**: Required for Capsule hooks (`blink-query` npm package)
- **Go 1.20+** (optional): For building dependency analysis tools (`query-deps`, `impact-analysis`, `progressive-reader`)

## RULES

1. **Directory structure**: NEVER create files in `.claude/`. Create in source dirs: `tools/`, `hooks/`, `scripts/`. The `.claude/` directory is generated by install.
2. **Tool enforcement** (enforced by PreToolUse hook):
   - Dependencies/imports: `bash $HOME/.claude/cck/tools/query-deps/query-deps.sh <file>`
   - Impact of changes: `bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh <file>`
   - Circular deps: `bash $HOME/.claude/cck/tools/find-circular/find-circular.sh`
   - Dead code: `bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh`
   - File search: `Glob` -- Code search: `Grep`
   - Large files (>50KB): `$HOME/.claude/bin/progressive-reader --path <file> --list`
   - Capsule context: `bash $HOME/.claude/cck/tools/context-query/context-query.sh <command> [args]`
     - Read: `search <term>`, `files`, `agents`, `sessions`, `recent`, `stats`
     - Write: `save <ns> <title> <summary> [type]`, `update <search> <new-summary>`
   - NEVER use Task/Explore for dependency queries, file search, or code search.
3. **Agent routing**: Use specialized agents via Task tool. Spawn in PARALLEL when independent.
   - Errors/bugs: `error-detective` | Debugging: `debugger` | Code review: `code-reviewer`
   - Refactoring: `refactoring-specialist` | Architecture: `architecture-explorer`
   - Security: `security-engineer` | Database: `database-navigator` | Git: `git-workflow-manager`
   - Production: `devops-sre` | Design: `brainstorm-coordinator`
   - 18 agents total available.
4. **Skills**: `/workflow` (complex tasks), `/debug` (errors/bugs), `/deep-context` (understand codebase), `/code-review` (pre-commit), `/crew` (parallel multi-branch teams). Auto-activate on keywords.
5. **Production safety**: All sub-agents are read-only (Read, Grep, Glob only). No Edit/Write/Bash.

## Crew Mode (Agent Teams)

For parallel multi-branch work, use the `/crew` skill. It handles team setup, worktree creation, and teammate spawning automatically.

**When to use crews** (not regular sub-agents):
- 2+ independent workstreams that benefit from separate git branches
- Work that should happen in parallel on isolated worktrees
- Tasks where teammates need their own branch to commit on

**Config**: `.crew-config.json` in project root defines team profiles, teammates, roles, and branches.
**CLI**: `cck crew init|decompose|start|stop|status|doctor|activity|gc|discoveries|merge-preview|merge` for manual control.
**Roles**: `developer`, `reviewer`, `tester`, `architect` — set defaults for model, mode, and focus.
**Staleness**: Configurable via `stale_after_hours` (default 4h). Teammates resume if still active.
**Crew grouping**: Config supports `crews` array to group teammates (e.g. frontend, backend). Use `--crew <name>` to filter commands.

Key rule: Only crew teammates use git worktrees. Regular sub-agents (Task tool) work in the main project directory.
**Requires**: Agent teams enabled in Claude Code. Setup guide: https://code.claude.com/docs/en/agent-teams

## Context System (Capsule)

Context is handled **fully automatically**. The JS hooks capture everything:

| Hook | Trigger | What It Captures |
|------|---------|-----------------|
| `session-start.js` | Session begins | Injects last session summary, recent files, team activity |
| `post-tool-use.js` | After Read/Write/Edit/Task | File operations (META), sub-agent invocations (SUMMARY) |
| `session-end.js` | Session ends | Session summary with file count, agent count |
| `pre-compact.js` | Before auto-compact | Saves session continuity document while full context is still available |
| `post-compact.js` | After auto-compact | Restores session continuity and injects saved context |
| `pre-tool-use-read.sh` | Before Read tool calls | Large file blocking (>50KB), recent-read warnings, capsule context suggestions |
| `pre-tool-use-task.sh` | Before Task tool calls | Dependency enforcement, file search suggestions, context-librarian suggestions |
| `subagent-start.js` | Subagent spawned | Injects crew context and relevant discoveries into subagent session |
| `teammate-idle.js` | Teammate goes idle | Saves teammate state, triggers handoff context capture |
| `worktree-lifecycle.js` | Worktree created/removed | Registers/deregisters worktree in global registry, updates crew state |
| `stop-failure.js` | Response stops with failure | Captures failure context, saves diagnostic info for next session |
| `stop.sh` | After responses | Quality check |

### Capsule Record Types

| Type | Meaning | Consumption Instruction |
|------|---------|------------------------|
| `SUMMARY` | Read the summary directly, you have what you need | Sub-agent findings, discoveries |
| `META` | Structured data (JSON content field) | File operations, session metadata, config |
| `COLLECTION` | Browse children, pick what's relevant | Groups of related records |
| `SOURCE` | Summary here, fetch source if you need depth | External references |
| `ALIAS` | Follow the redirect to the target record | Pointers |

### Capsule Namespace Reference

**Solo mode:**
```
session/{session_id}/files       -- File operation records (META)
session/{session_id}/subagents   -- Sub-agent invocation records (SUMMARY)
session                          -- Session summary records (META)
discoveries                      -- Architectural discoveries
```

**Crew mode** (Agent Teams with worktrees, shared `capsule.db`):
```
crew/{teammate_name}/session/{session_id}/files       -- Teammate file ops
crew/{teammate_name}/session/{session_id}/subagents   -- Teammate sub-agents
crew/{teammate_name}/session                          -- Teammate session summaries
crew/_shared/discoveries                              -- Shared team discoveries
```

## Tool Enforcement Details

### Dependency Analysis (ALWAYS use these tools)

| Question | Command |
|----------|---------|
| What imports file X? | `bash $HOME/.claude/cck/tools/query-deps/query-deps.sh <file>` |
| What breaks if I change X? | `bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh <file>` |
| Circular dependencies? | `bash $HOME/.claude/cck/tools/find-circular/find-circular.sh` |
| Dead/unused code? | `bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh` |

NEVER use Task/Explore for dependency queries. These tools use a pre-built graph — instant vs sequential scanning.

### Capsule Context Query (mid-session access)

| Question | Command |
|----------|---------|
| Search past context | `bash $HOME/.claude/cck/tools/context-query/context-query.sh search <term>` |
| Recent file operations | `bash $HOME/.claude/cck/tools/context-query/context-query.sh files` |
| Sub-agent history | `bash $HOME/.claude/cck/tools/context-query/context-query.sh agents` |
| Session summaries | `bash $HOME/.claude/cck/tools/context-query/context-query.sh sessions` |
| Save a discovery | `bash $HOME/.claude/cck/tools/context-query/context-query.sh save discoveries "<title>" "<summary>"` |
| Update a record | `bash $HOME/.claude/cck/tools/context-query/context-query.sh update "<title>" "<new summary>"` |

### Large File Navigation (>50KB)

1. Discover structure: `$HOME/.claude/bin/progressive-reader --path <file> --list`
2. Read specific chunk: `$HOME/.claude/bin/progressive-reader --path <file> --chunk N`

Languages with AST parsing: TypeScript, JavaScript, Python, Go. Token savings: 75-97%.

If you get `MaxFileReadTokenExceededError`, IMMEDIATELY switch to progressive-reader.