majiayu000 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)
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-file-change.sh" }]
},
{
"matcher": "Edit",
"hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-file-change.sh" }]
},
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-bash-event.sh" }]
}
]
}
}
Note: Uses
$CLAUDE_PROJECT_DIRfor portable paths (resolved at runtime by Claude Code).
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:
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:
# 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
{
"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)
# 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
/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
# 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:
# 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
- Check hooks exist:
ls .claude/hooks/*.sh - Check hooks.json:
cat hooks/hooks.json - Check scripts are executable:
chmod +x .claude/hooks/*.sh
Stale session blocking
# Check what's there
cat .auto-loop/checkpoint.json | jq '.status'
# Force restart
/auto-loop --force "New task"
Changelog too large
# Manual archive
/changelog --archive
# Or clear
/changelog --clear