changelog · git:20260116.fa09a39 · 2026-01-16 · sha256 b4330bab73d28e81
changelog git:20260116.fa09a39A
Immutable. This exact content never changes and is served at /api/v1/blob/b4330bab73d28e81.
---
name: changelog
description: View and manage the runtime changelog for observability
user-invocable: true
---
# Changelog Skill
> **Status: Experimental**
> This feature uses Claude Code's PostToolUse hooks. The hook interface may change in future versions.
> If hooks don't trigger as expected, events can still be logged manually via auto-loop prompts.
Runtime observability changelog for tracking all changes during development sessions.
---
## Overview
This skill provides an **automated** changelog system that:
- **Automatically** records file changes via PostToolUse hooks
- **Automatically** logs test results when tests are run
- **Automatically** records git commits
- **Automatically** rotates when exceeding 500 lines
- Enables subagents to understand context from previous actions
- Supports session recovery and debugging
---
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Observability System │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────────────────────┐ │
│ │ Write/Edit │ │ Bash │ │
│ │ Tool │ │ (test/commit/general) │ │
│ └──────┬──────┘ └──────────────┬──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PostToolUse Hooks │ │
│ │ log-file-change.sh log-bash-event.sh │ │
│ └─────────────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ _lib-changelog.sh │ │
│ │ • log_event() • rotate_if_needed() │ │
│ │ • archive_changelog() • clear_changelog() │ │
│ └─────────────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ .director-mode/changelog.jsonl │ │
│ │ │ │
│ │ {"event_type":"file_created",...} │ │
│ │ {"event_type":"test_pass",...} │ │
│ │ {"event_type":"commit",...} │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────┴─────────────┐ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ /changelog │ │ Subagents │ │
│ │ command │ │ code-reviewer │ │
│ │ │ │ debugger │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Relationship with Checkpoint
| Aspect | Checkpoint | Changelog |
|--------|------------|-----------|
| Location | `.auto-loop/checkpoint.json` | `.director-mode/changelog.jsonl` |
| Purpose | Current state snapshot | Historical event stream |
| Question answered | "Where am I now?" | "How did I get here?" |
| Used by | Stop Hook (continue/stop decision) | Subagents (context) |
| Format | Single JSON object | JSONL (append-only) |
| Persistence | Overwritten each iteration | Accumulated, then rotated |
**They complement each other:**
- **Checkpoint** = Save point for resume
- **Changelog** = Audit trail for observability
---
## Automatic Logging via Hooks
### Hook Configuration (`.claude/settings.local.json`)
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "/path/to/project/.claude/hooks/log-file-change.sh" }]
},
{
"matcher": "Edit",
"hooks": [{ "type": "command", "command": "/path/to/project/.claude/hooks/log-file-change.sh" }]
},
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "/path/to/project/.claude/hooks/log-bash-event.sh" }]
}
]
}
}
```
> **Note**: Paths are converted to absolute paths during `install.sh` execution.
### Hook Scripts
| Script | Trigger | Events Logged |
|--------|---------|---------------|
| `log-file-change.sh` | Write, Edit | `file_created`, `file_modified` |
| `log-bash-event.sh` | Bash | `test_pass`, `test_fail`, `commit` |
---
## Automatic Rotation
**Prevents unbounded growth:**
```bash
MAX_LINES=500
# When changelog exceeds 500 lines:
# 1. Move current to changelog.YYYYMMDD_HHMMSS.jsonl
# 2. Start fresh changelog.jsonl
# 3. Log rotation event
```
**Result:**
```
.director-mode/
├── changelog.jsonl ← Current (< 500 lines)
├── changelog.20250113_103000.jsonl ← Archived
├── changelog.20250112_150000.jsonl ← Archived
└── changelog.20250111_090000.jsonl ← Archived
```
---
## Session Conflict Prevention
**Only one auto-loop session per project:**
```bash
# When starting /auto-loop:
if checkpoint exists AND status == "in_progress":
→ Block with message:
"Found interrupted session at iteration #N"
"Use --resume or --force"
```
**Options:**
- `/auto-loop --resume` → Continue with existing checkpoint + changelog
- `/auto-loop --force "task"` → Archive old, start fresh
---
## Event Schema
```json
{
"id": "evt_1705142400_12345",
"timestamp": "2025-01-13T10:30:00.000Z",
"event_type": "file_modified",
"agent": "hook",
"iteration": 3,
"summary": "file_modified: Login.tsx",
"files": ["src/components/Login.tsx"]
}
```
### Event Types
| Type | Source | Description |
|------|--------|-------------|
| `file_created` | Hook (Write) | New file created |
| `file_modified` | Hook (Edit) | File edited |
| `test_pass` | Hook (Bash) | Tests passing |
| `test_fail` | Hook (Bash) | Tests failing |
| `commit` | Hook (Bash) | Git commit made |
| `session_start` | auto-loop | Session begins |
| `session_end` | auto-loop | Session completes |
| `changelog_rotated` | System | Changelog was rotated |
---
## Subagent Integration
### code-reviewer
Before review, checks changelog for:
- What files were changed recently
- What iteration we're on
- Recent test results
### debugger
Before debugging, checks changelog for:
- When errors first occurred
- What files changed before errors
- Pattern of test failures
---
## Core Functions (`_lib-changelog.sh`)
```bash
# Log an event
log_event "file_created" "Created Login.tsx" "hook" '["src/Login.tsx"]'
# Archive current changelog
archive_changelog
# Clear changelog
clear_changelog
# List archives
list_archives
```
---
## Querying
### Via Command
```bash
/changelog # Recent 10 events
/changelog --summary # Statistics
/changelog --type test # Filter by type
/changelog --list-archives # Show old changelogs
/changelog --export log.json
```
### Via Bash
```bash
# Last 5 events
tail -n 5 .director-mode/changelog.jsonl | jq '.'
# All file changes
grep '"event_type":"file_' .director-mode/changelog.jsonl
# Count by type
jq -r '.event_type' .director-mode/changelog.jsonl | sort | uniq -c
```
---
## Example Session Flow
```
1. /auto-loop "Implement login"
→ Check: No existing session
→ Archive old changelog (if > 100 lines)
→ Create checkpoint (status: in_progress)
→ Log: session_start
2. TDD Iteration #1
→ Write test file
→ Hook logs: file_created
→ Run tests (fail)
→ Hook logs: test_fail
→ Write implementation
→ Hook logs: file_created
→ Run tests (pass)
→ Hook logs: test_pass
→ Commit
→ Hook logs: commit
3. Session interrupted (crash/exit)
→ Checkpoint remains: iteration=1, status=in_progress
→ Changelog has full history
4. /auto-loop "something"
→ Check: Found in_progress session!
→ Block: "Use --resume or --force"
5. /auto-loop --resume
→ Read checkpoint: iteration=1
→ Read changelog: understand context
→ Continue from iteration #2
```
---
## Installation
Hooks are installed with Director Mode Lite:
```bash
# After install, verify:
ls .claude/hooks/
# → auto-loop-stop.sh
# → _lib-changelog.sh
# → log-bash-event.sh
# → log-file-change.sh
# → pre-tool-validator.sh
cat .claude/settings.local.json | jq '.hooks'
```
---
## Troubleshooting
### Events not logged
1. Check hooks exist: `ls .claude/hooks/*.sh`
2. Check hooks.json: `cat hooks/hooks.json`
3. Check scripts are executable: `chmod +x .claude/hooks/*.sh`
### Stale session blocking
```bash
# Check what's there
cat .auto-loop/checkpoint.json | jq '.status'
# Force restart
/auto-loop --force "New task"
```
### Changelog too large
```bash
# Manual archive
/changelog --archive
# Or clear
/changelog --clear
```