| name | flow-changelog-audit |
| description | Audit the Claude Code CHANGELOG.md for plugin-relevant changes. Builds FLOW's integration surface model, fetches new changelog entries, categorizes as Adopt/Remove/Adapt, and files issues for approved items. |
FLOW Changelog Audit
Audit the Claude Code CHANGELOG.md for changes relevant to the FLOW plugin.
Maintainer-only — runs in the FLOW source repo.
The skill builds a deep understanding of FLOW's integration surface before
reading the changelog, then assesses each entry against that model to
recognize opportunities that shallow keyword matching would miss.
Announce
Print:
```text
──────────────────────────────────────────────────
FLOW v1.0.1 — changelog-audit — STARTING
──────────────────────────────────────────────────
```
Assessment Categories
Every changelog entry relevant to FLOW falls into one of three categories:
Adopt — What can FLOW do now that it couldn't before? New platform
capabilities that unlock features or improve existing ones. Example:
updatedInput on PreToolUse enabling programmatic AskUserQuestion
interception.
Remove — What can FLOW stop doing because Claude Code does it natively
now? Code FLOW carries that the platform has made redundant. Removals are
often the highest value: less code, less maintenance, fewer failure modes.
Adapt — What should FLOW do differently because the platform changed?
A hook event that now fires at a different time, a permission syntax that
deprecated the old form, a frontmatter field that replaces a workaround.
Not relevant — After investigation, the entry does not apply to
FLOW's integration surface. One-line explanation of why.
Step 0 — Build integration surface model
Before reading the changelog, build a mental model of how FLOW integrates
with Claude Code. Read each of the following files using the Read tool and
note what Claude Code APIs, features, and capabilities FLOW currently uses.
Hook registrations. Read hooks/hooks.json. For each hook event
(SessionStart, PreToolUse, PostToolUse, PostCompact, Stop, StopFailure),
note the matchers and which scripts handle them.
Hook scripts. Read each script referenced in hooks/hooks.json:
hooks/session-start.sh — what Claude Code session events it handlessrc/hooks/validate_pretool.rs — what PreToolUse capabilities it usessrc/hooks/validate_worktree_paths.rs — what PreToolUse capabilities it usessrc/hooks/validate_ask_user.rs — what PreToolUse capabilities it uses (especially updatedInput and permissionDecision)lib/clear-blocked.py — what PostToolUse capabilities it useslib/post-compact.py — what PostCompact capabilities it useslib/stop-continue.py — what Stop hook capabilities it useslib/stop-failure.py — what StopFailure hook capabilities it uses
Skill frontmatter. Read the YAML frontmatter block (between the
opening and closing --- delimiters) of 3 plugin skills:
skills/flow-start/SKILL.md, skills/flow-code/SKILL.md, and
skills/flow-issues/SKILL.md. Note which frontmatter fields FLOW uses.
Agent frontmatter. Read the YAML frontmatter block of
agents/ci-fixer.md. Note which agent frontmatter fields FLOW uses
(name, description, tools, maxTurns, hooks).
Permission surface. Read .claude/settings.json. Note the permission
structure: defaultMode, permissions.allow, permissions.deny, exclude.
Installation surface. Read lib/prime-setup.py. Note what Claude Code
configuration surfaces it writes to during project setup.
After reading all files, summarize the integration surface model in your
response. This summary is the foundation for Step 4 assessments.
Step 1 — Read stored version
Use the Read tool to read config.json at the repo root. Extract the
claude_code_audited field value — this is the last version FLOW was
audited against.
Display the stored version in your response.
Step 2 — Fetch changelog
Use WebFetch to fetch the Claude Code changelog:
URL: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
Prompt: "Extract all version entries. For each version, return the version
number and the full entry text. Start from the most recent version and go
backwards. Return every entry."
From the result, identify all versions newer than the stored version from
Step 1. These are the entries to audit.
If no new versions exist since the stored version, print the Done banner
and stop.
Display the count of new versions found.
Step 3 — Filter entries
Filter the new version entries for plugin-relevant keywords. An entry is
relevant if it contains any of these terms:
hook, frontmatter, agent, skill, worktree, plugin,
PreToolUse, PostToolUse, PostCompact, Stop, SessionStart,
StopFailure, permission, sandbox, matcher, manifest,
userConfig, AskUserQuestion, updatedInput, permissionDecision,
maxTurns, bypassPermissions, defaultMode, exclude, deny,
MCP, subagent, sub-agent
This keyword list should be expanded as new Claude Code surface areas
emerge. When in doubt, include the entry — false positives are filtered
in Step 4, but false negatives are missed opportunities.
Display the count of relevant entries found. If zero, print the Done
banner and stop.
Step 4 — Deep assessment
For each relevant entry from Step 3, assess it against the integration
surface model from Step 0.
The critical rule: grep for the specific new API surface mentioned
in each changelog entry, not just the parent feature. "FLOW uses
PreToolUse" does not mean "FLOW uses every capability of PreToolUse."
If a changelog entry mentions a new parameter, return value, or behavior
on an existing hook, grep for that specific parameter name in the FLOW
codebase using the Grep tool.
For each entry, determine:
Adopt — The entry describes a capability that FLOW's hooks, skills,
or agents do not currently use. Grep confirms the specific new API
surface does not appear in the codebase. The capability would enable
something FLOW cannot do today or would improve an existing feature.
Remove — The entry describes something that Claude Code now handles
natively, making FLOW's manual implementation redundant. Grep confirms
FLOW currently implements this manually. The FLOW code could be deleted
or simplified.
Adapt — The entry changes the behavior or API of something FLOW
currently relies on. Grep confirms FLOW uses the affected API. FLOW
may need to change how it uses it to remain correct or optimal.
Not relevant — After grepping, the entry does not apply to FLOW's
integration surface. One-line explanation of why.
In your rationale, always name the specific FLOW file(s) affected and
explain the connection.
Step 5 — Present categorized tables
Present the findings in your response as three markdown tables. Skip any
table where the category has zero entries.
Adopt
| # | Version | Entry | Rationale |
|---|
| 1 | v2.X.Y | Brief description of the change | Which FLOW files are affected and what the opportunity is |
Remove
| # | Version | Entry | Rationale |
|---|
| 2 | v2.X.Y | Brief description of the change | Which FLOW code becomes redundant and why |
Adapt
| # | Version | Entry | Rationale |
|---|
| 3 | v2.X.Y | Brief description of the change | Which FLOW code needs updating and how |
Number rows sequentially across all three tables (not restarting per table).
After the tables, list entries categorized as "Not relevant" with
one-line explanations.
Step 6 — File issues
Do NOT file any issues without explicit user approval. Do NOT proceed
to Step 7 without completing this step. Do NOT take any action outside
this skill flow.
Present the Adopt, Remove, and Adapt items from Step 5 and ask the user
which items to file as issues. Use AskUserQuestion:
"Which items should I file as issues? List the numbers, or say 'all'
or 'none'."
Wait for the user's response before taking any action.
For each approved item, invoke /flow:flow-explore with a description
that includes the version, the changelog entry, the assessment category
(Adopt, Remove, or Adapt), and the rationale from Step 5.
If the user says "none", skip to Step 7.
Step 7 — Update version marker
Do NOT update `config.json` without explicit user confirmation. Do NOT
commit without explicit user confirmation. Do NOT take any action outside
this skill flow.
Substitute the actual latest version from Step 2 in the prompt below,
then use AskUserQuestion:
"Audit complete. Update config.json to mark version <latest version>
as audited and commit?"
Options:
- Yes, update and commit
- No, leave the version marker unchanged
Wait for the user's response before taking any action.
If approved, use the Edit tool to update the claude_code_audited value
in config.json to the latest version audited in Step 2.
Then invoke /flow:flow-commit to commit the change.
If denied, skip the update.
Done
Print:
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ FLOW v1.0.1 — changelog-audit — COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
Rules
- Read-only until Step 6 — never create, edit, or close issues before the HARD-GATE
- Never update config.json before the Step 7 HARD-GATE
- Always grep for the specific new API surface, not just the parent feature name
- Build the integration surface model fresh each run — never rely on cached knowledge
- When in doubt about relevance, include the entry — false positives cost one line in a table, false negatives cost missed opportunities
- The keyword list in Step 3 is maintained in this skill — expand it when new Claude Code surface areas emerge
- Never add Co-Authored-By trailers or attribution lines
