workflow-changelog

# Workflow Changelog

You are a coordinator for the claude-code-hooks project. Your job is to launch two research agents in parallel, wait for their results, merge findings, and present a unified report.

**Versions to check:** `$ARGUMENTS` (default: 10 if empty or not a number)

This is a **read-then-report** workflow. Launch agents, merge results, and produce a report. Only take action if the user approves.

---

## Phase 0: Launch Both Agents in Parallel

**Immediately** spawn both agents using the Task tool **in the same message** (parallel launch):

### Agent 1: workflow-changelog-agent

Spawn using `subagent_type: "workflow-changelog-agent"`. Give it this prompt:

> Research the claude-code-hooks project for changelog drift. Check the last $ARGUMENTS versions (default: 10).
>
> Fetch these 3 external sources:
> 1. Hooks Reference: https://code.claude.com/docs/en/hooks
> 2. Hooks Guide: https://code.claude.com/docs/en/hooks-guide
> 3. Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
>
> Then read all local repository files (settings, hooks.py, config, README, HOOKS-README, install settings, presentation) and analyze differences. Return a structured findings report covering missing hooks, configuration drift, version mismatches, hook behavior changes, bug fixes, matcher accuracy, presentation staleness, agent frontmatter hooks, and schema hook discovery (hidden hooks in settings.json schema propertyNames enum not in docs).

### Agent 2: claude-code-guide

Spawn using `subagent_type: "claude-code-guide"`. Give it this prompt:

> Research the latest Claude Code hooks system. I need you to find:
> 1. The complete list of all currently supported hook events (e.g. PreToolUse, PostToolUse, Stop, etc.) with their descriptions
> 2. Any new hooks or hook changes introduced in recent Claude Code versions
> 3. New hook input fields, matcher values, or configuration options added recently
> 4. Any new hook types (command, prompt, agent) or new environment variables
> 5. Changes to agent/skill frontmatter hook support
> 6. Any bug fixes related to hooks
> 7. New features in Claude Code that relate to hooks (e.g. new tool names for matchers, new subagent types)
>
> Be thorough — search the web, fetch docs, and provide concrete version numbers and details for everything you find.

Both agents run independently and will return their findings.

---

## Phase 0.5: Read Verification Checklist

**While agents are running**, read `changelog/verification-checklist.md`. This file contains accumulated verification rules — each rule specifies what to check, at what depth, and against which source. Every rule MUST be executed during Phase 2. The checklist is the project's regression test suite for drift detection.

---

## Phase 1: Read Previous Changelog Entries

**Before merging findings**, read the file `changelog/changelog.md` to get the last 10 changelog entries. Each entry is separated by `---`. Parse the priority actions from those previous entries so you can compare them against the current findings. This lets you identify:
- **Recurring items** — issues that appeared before and are still unresolved
- **Newly resolved items** — issues from previous runs that are now fixed
- **New items** — issues that appear for the first time in this run

---

## Phase 2: Merge Findings & Generate Report

**Wait for both agents to complete.** Once you have:
- **workflow-changelog-agent findings** — detailed repo analysis with local file reads, external doc fetches, and drift detection
- **claude-code-guide findings** — independent research on latest Claude Code hooks, features, and changes

Cross-reference the two. The workflow-changelog-agent provides repo-specific drift analysis, while the claude-code-guide agent may surface things it missed (e.g. very recent changes, undocumented features, or context from web searches). Flag any contradictions between the two for the user to resolve.

**Execute the verification checklist:** For every rule in `changelog/verification-checklist.md`, perform the check at the specified depth using the agent findings as source data. Include a **Verification Log** section in the report showing each rule's result:

```
Verification Log:
Rule # | Category         | Depth         | Result | Notes
1      | Hook Options     | field-level   | PASS   | All fields match
2      | Matcher Values   | content-match | FAIL   | SubagentStart values differ
...
```

**Update the checklist if needed:** If a finding reveals a new type of drift that no existing checklist rule covers (or covers at insufficient depth), append a new rule to `changelog/verification-checklist.md`. The rule must include: category, what to check, depth level, what source to compare against, date added, and the origin (what error prompted this rule). Do NOT add rules for one-off issues that won't recur.

Also compare the current findings against the previous changelog entries (from Phase 1). For each priority action, mark it as:
- `NEW` — first time this issue appears
- `RECURRING` — appeared in a previous run and is still unresolved (include which run date it first appeared)
- `RESOLVED` — appeared in a previous run but is now fixed (include resolution date)

Produce a structured report with these sections:

1. **New Hooks to Add** — Missing hooks with version and `/workflows:workflow-add-hook` command
2. **Configuration Drift** — Inconsistencies across files with specific fixes
3. **Version & Count Mismatches** — Table showing current vs expected for each location
4. **Documentation Updates** — Outdated docs with changelog version references
5. **Bug Fixes & Workaround Status** — Known issues with fix status
6. **New Features to Consider** — Relevant new features from changelog
7. **Matcher & Schema Accuracy** — Per-hook verification status
8. **Hook Types & Environment Variables** — Documentation coverage status
9. **Removed/Deprecated Hooks** — Hooks in repo but not in docs
10. **Presentation Update