changelog

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

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

# 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