v0.4.2 — version-pointer comment in refine.md

Patch release over v0.4.1. Developer-ergonomics fix; no behavioral changes to the refiner.

Added

• Version-pointer comment at the top of refine.md. An HTML comment immediately after the YAML frontmatter names the release version and links to its GitHub tag. Devs reading a raw file, a local install, or a shared copy can identify the upstream version at a glance — and confirm divergence by running shasum -a 256 refine.md against the release hash below.

Changed

• Install hash bumped to the v0.4.2 value. README badge and install URLs moved to v0.4.2.

Install

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/refine.md \
  https://raw.githubusercontent.com/ICJIA/claude-code-refine/v0.4.2/refine.md
echo "e16bdba67959519f2d3f07ec7ee6c3b2b0df0db3db90d2b84e15c4bf8869410c  $HOME/.claude/commands/refine.md" | shasum -a 256 -c

Restart your Claude Code session so it picks up the new command.

Verification

SHA-256 of refine.md at this tag:

e16bdba67959519f2d3f07ec7ee6c3b2b0df0db3db90d2b84e15c4bf8869410c  refine.md

See CHANGELOG.md for the full history and SECURITY_REVIEW.md for the red/blue-team audit landed in v0.4.0.

v0.4.1 — YAML frontmatter fix + install checksum

Patch release over v0.4.0. No behavioral changes to the refiner itself — frontmatter and install-docs fixes only.

Fixed

• YAML frontmatter parse error in refine.md. GitHub (and any strict YAML parser) rejected the argument-hint: [47|46] [rough prompt] line because | is not a valid separator inside a YAML flow sequence. Quoted the value as "[47|46] [rough prompt]" so it parses as a plain string. Bug has been present since v0.1.0.

Changed

• Install checksum published. README.md now pins the shasum -a 256 -c verification step to the real v0.4.1 hash instead of the <sha256-from-release> placeholder shipped in v0.4.0.
• README badge and install URLs bumped to v0.4.1.

Install

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/refine.md \
  https://raw.githubusercontent.com/ICJIA/claude-code-refine/v0.4.1/refine.md
echo "cf1f03648b64da1562df7eca1beff492be1f9ca2e2f739f1a3b9c9978d5b8f87  $HOME/.claude/commands/refine.md" | shasum -a 256 -c

Restart your Claude Code session so it picks up the new command.

Verification

SHA-256 of refine.md at this tag:

cf1f03648b64da1562df7eca1beff492be1f9ca2e2f739f1a3b9c9978d5b8f87  refine.md

See CHANGELOG.md for the full history and SECURITY_REVIEW.md for the red/blue-team audit landed in v0.4.0.

v0.4.0 — security hardening + red/blue-team audit

Superseded by v0.4.1, which fixes a pre-existing YAML frontmatter parse error and publishes the real install checksum. Prefer v0.4.1 for new installs.

Security-focused release. Remediates the ten red/blue-team findings in SECURITY_REVIEW.md; adds a new ## Security section to the README.

Security

• Red-team / blue-team audit published as SECURITY_REVIEW.md. Full threat model, input-surface inventory, ten red-team findings with severities and reproductions, blue-team mitigations, documentation-drift notes, recommendations, and per-finding remediation status.
• Read-scope policy in refine.md Step 1. The refiner refuses to open files outside the current working directory or matching a secret-file denylist (.env*, *.pem, *.key, id_rsa*, id_ed25519*, id_ecdsa*, .aws/**, .ssh/**, .gnupg/**, .netrc, .npmrc, .pypirc). Closes RT-03, RT-04.
• Data-not-instructions framing in Step 1 and Step 1a. Rough-prompt text, file contents, and multimodal attachment transcripts are inputs to summarize, not instructions to execute; override attempts are surfaced in Assumptions to confirm. Closes RT-01, RT-06.
• Immutable approval gate in Step 4. The Execute this refined prompt? (yes / edit / cancel) question is fixed verbatim; reworded or alternate answers are rejected. Closes RT-02.
• Trust-sensitive label on the "Project conventions to apply" block, mirrored as a Customize trust note in the README. Closes RT-07.
• Mode-token normalization (strip surrounding whitespace/quotes, apply NFKC). Closes RT-08.

Changed

• Install pinned to a release tag and checksummed. Install command now uses the v0.4.0 tag (not main) and shows a shasum -a 256 -c verification step. Closes RT-05.
• "No API calls" wording softened in the How-it-works section. Closes RT-09.
• Project-scoped-install warning surfaced in the main Install section. Closes RT-10.

Added

• New ## Security section in README.md (with a matching TOC entry) summarizing the inputs the refiner reads, the defenses baked into the template, what sits outside scope, and linking to SECURITY_REVIEW.md.

See CHANGELOG.md for the full version history.

v0.3.0

What changed

Narrowed Step 1's default read scope in refine.md to cut token/context overhead on every /refine invocation.

Before (v0.2.0)

Step 1 read CLAUDE.md, package.json, README, and any obviously relevant source files on every invocation — regardless of whether the rough prompt needed that context.

After (v0.3.0)

Step 1 reads CLAUDE.md and package.json by default. It reads README.md, CHANGELOG.md, or any source file only when:

• the rough prompt names the file, or
• the ambiguities identified in Step 2 cannot be resolved from CLAUDE.md and package.json alone.

When the narrowed default isn't enough, Step 2a's interactive check ("what should I look at?") closes the gap — at the cost of one short turn, paid only when needed.

Impact on token / context usage

• Typical project: ~3,000–5,000 tokens saved per /refine invocation.
• Large repo with a verbose README: savings scale linearly — can exceed 10,000 tokens per run.
• Small project (minimal CLAUDE.md/package.json): savings are smaller but the tool is also already cheap there.

For context: refinement overhead on a 3-file reference project measured ~9,800 tokens pre-change. The same workload under v0.3.0 drops to ~5,000–6,000 tokens — still a real cost, but now proportional to what refinement actually buys (a reviewable plan before execution).

What did NOT change

• File location: still a single markdown slash command, installed at ~/.claude/commands/refine.md (global) or <project>/.claude/commands/refine.md (project-scoped).
• Argument parsing, mode templates (47 / 46), style rules, Step 2 / 2a / 3 / 4 logic, conventions section, install steps, frontmatter — all unchanged.
• One file, no dependencies, no build step.

Also in this release

• README.md "How it works" step 1 updated to reflect the narrower default.
• README release badge bumped to v0.3.0.

Upgrade

curl -o ~/.claude/commands/refine.md \
  https://raw.githubusercontent.com/ICJIA/claude-code-refine/main/refine.md

Restart your Claude Code session to pick up the new template.

---

Full changelog: https://github.com/ICJIA/claude-code-refine/blob/main/CHANGELOG.md
Compare: v0.2.0...v0.3.0

v0.2.0 — attached-file handling

Added

• Attached-file handling (Step 1a in refine.md). When $ARGUMENTS contains file paths (CSV, PNG/JPG/screenshot, PDF, JSON, log, etc.), the refiner now opens them with the appropriate tool and surfaces what it finds — column names and sample rows for tabular data, visible UI/layout/text for images, summarized content for documents, structure for code/config. File paths are carried verbatim into the refined prompt's Context section, and promoted to Goal/Steps/Approach when the file is the central input (e.g. a Siteimprove CSV to process or a PNG of a UI design to replicate).

Changed

• README badge and Releases section bumped to v0.2.0.
• "How it works" procedure in README updated to mention attached-file handling.

---

Full changelog: CHANGELOG.md

v0.1.1 — docs-only release

Docs-only release. No changes to refine.md behavior.

Changed

• Expanded Credits section in README with a linked Augment Code reference, Context Engine framing, and a "why a refinement step matters" rationale targeting both casual adopters and contributors.
• Softened What it does summary so it covers both mode-47 and mode-46 output shapes.
• Renumbered the How it works procedure to 1–5 (was 1, 2, 2a, 3, 4; the 2a item didn't render cleanly as an ordered-list continuation).
• Added Contents (table of contents) and a second worked example (rate-limiting the login endpoint), with mode 46 and mode 47 outputs paired in collapsible sections for each of the two examples.
• Updated README release badge and Releases section to reflect v0.1.1.

Upgrade

No action required. If you've already installed refine.md from v0.1.0, the command works identically. The changes are in README.md and CHANGELOG.md only.

v0.1.0 — initial release

Initial release of /refine, a prompt-enhancement slash command for Claude Code with mode branching for Claude Opus 4.6 (intent-focused) and 4.7 (exhaustive-spec).

Added

• Mode 47 — exhaustive, literal refinement tuned for Claude Opus 4.7.
• Mode 46 — intent-focused, fuzzier refinement tuned for Claude Opus 4.6.
• Default to mode 47 when no mode token is supplied; defaulted mode is flagged in the refined output.
• Mode-indicator banner (> **Tuned for: Claude Opus 4.x ...**) as the first line of every refined prompt.
• Skip-refinement check: if a rough prompt is already well-specified, the command asks whether to refine or execute as-is.
• Customizable "Project conventions to apply" section in refine.md (mode 47 restates verbatim; mode 46 invokes by name).
• README with install steps, usage example, "How it works" walkthrough, collapsible advanced-usage section, and roadmap.
• MIT LICENSE (© Illinois Criminal Justice Information Authority).

Install

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/refine.md \
  https://raw.githubusercontent.com/ICJIA/claude-code-refine/main/refine.md

See the README for full documentation.