From adf7457e635cd4145839b523b3d1caa7347c8592 Mon Sep 17 00:00:00 2001 From: Will Pike <6687499+pike00@users.noreply.github.com> Date: Tue, 12 May 2026 15:10:03 -0500 Subject: [PATCH 1/3] chore(release): bump to 0.5.0 and document release process Bumps both manifests (src/dot-claude-plugin/plugin.json and .claude-plugin/marketplace.json) to 0.5.0 so the seven content changes since 0.4.0 (global numbering, Suggested Fix column, format regression tests, eval max_tokens bump, .env gitignore) reach marketplace users. Adds CLAUDE.md with a release checklist and semver guidance, and adds a matching Releasing section to the README so contributors and Claude Code sessions know what files to bump. --- .claude-plugin/marketplace.json | 2 +- CHANGELOG.md | 15 +++++++ CLAUDE.md | 66 +++++++++++++++++++++++++++++++ README.md | 18 +++++++++ src/dot-claude-plugin/plugin.json | 2 +- 5 files changed, 101 insertions(+), 2 deletions(-) create mode 100644 CLAUDE.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 343df47..415548c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "name": "look", "source": "./src", "description": "Sequential code review with fresh agent contexts. Runs multiple independent review passes to catch more issues.", - "version": "0.4.0", + "version": "0.5.0", "author": { "name": "HartBrook" }, "repository": "https://github.com/HartBrook/lookagain", "license": "MIT", diff --git a/CHANGELOG.md b/CHANGELOG.md index 11f57aa..85afcb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.5.0] - 2026-05-12 + +### Added + +- Global sequential numbering across all severity sections in `/look:again` aggregate summary tables, so issues can be referenced by ID (e.g. "fix #3, #5") across must_fix/should_fix/suggestion groups. +- "Suggested Fix" column in summary tables, providing a one-line fix preview alongside the existing detailed write-ups. +- Static format regression tests in `scripts/test.sh` enforcing the new numbering and Suggested Fix output contract. +- `.env` added to `.gitignore` so local `ANTHROPIC_API_KEY` files used for `make eval` / `make integration` cannot be committed accidentally. + +### Changed + +- Bumped promptfoo eval `max_tokens` to 4096 so reviewer outputs are not truncated mid-JSON for larger diffs. +- `/look:again` orchestrator and reviewer prompts updated to emphasize the global ID rules so passes produce stable, parseable output. +- Pipe and newline characters in Suggested Fix cells are now escaped so the markdown tables render correctly. + ## [0.4.0] - 2026-01-29 ### Changed diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b6d4d61 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,66 @@ +# CLAUDE.md + +Project-level instructions for Claude Code working in this repo. + +## What this is + +`lookagain` is a Claude Code plugin (published via the `hartbrook-plugins` marketplace) that runs sequential multi-pass code reviews. The main user-facing surface is the `/look:again` skill. + +## Layout + +- `src/skills/again/SKILL.md` - orchestrator prompt for `/look:again` +- `src/skills/tidy/SKILL.md` - `/look:tidy` cleanup skill +- `src/skills/lookagain-output-format/SKILL.md` - JSON output contract the reviewer subagent must follow +- `src/agents/lookagain-reviewer.md` - reviewer subagent definition +- `src/dot-claude-plugin/plugin.json` - plugin manifest (becomes `.claude-plugin/plugin.json` in the built dist) +- `.claude-plugin/marketplace.json` - marketplace manifest at repo root (what the marketplace fetches from `main`) +- `scripts/package.sh` - build script (renames `dot-*` -> `.*` and zips) +- `scripts/test.sh` - structural validation +- `evals/promptfooconfig.yaml` - behavioral evals + +## Editing rules + +- Skill prompts (`src/skills/**/SKILL.md`): use `$ARGUMENTS` (whole string) or `$ARGUMENTS[N]` (positional) only. Do not use `arguments:` frontmatter array or `$ARGUMENTS.` dot-access; neither is interpolated by Claude Code. See CONTRIBUTING.md "Writing Skill Prompts" for the full pattern. +- Every skill that uses `$ARGUMENTS` must have an `argument-hint` in frontmatter, a defaults table in the body, and a "log the resolved configuration" instruction. `make test` enforces this. +- User-triggered skills should set `disable-model-invocation: true` so Claude does not auto-fire them. + +## Tests + +- `make test` - structural validation, free, offline. Run before every commit. +- `make eval` - behavioral evals via promptfoo. Run after prompt or argument-handling changes. Needs `ANTHROPIC_API_KEY`. +- `make integration` - end-to-end review in a temp repo. Run after pipeline/output-format changes. Needs `ANTHROPIC_API_KEY`. + +## Release process + +The marketplace tracks `main` of this repo. There are no git tags or GitHub releases - bumping the version on `main` is what makes a new release visible to users. + +Checklist for cutting a release: + +1. Branch off `main`: `git checkout -b release/vX.Y.Z`. +2. Bump version in **both** manifest files (must stay in sync): + - `src/dot-claude-plugin/plugin.json` -> `"version": "X.Y.Z"` + - `.claude-plugin/marketplace.json` -> `"version": "X.Y.Z"` (inside `plugins[0]`) +3. Add a `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` under "Added"/"Changed"/"Fixed"/"Removed" using Keep a Changelog conventions. +4. Run `make test`. Fix anything it flags. +5. (Recommended for skill prompt changes) `make eval`. +6. (Recommended for orchestration/output-format changes) `make integration`. +7. Commit, push, open a PR against `main`. +8. After merge, end users update with: + ``` + /plugin marketplace update hartbrook-plugins + /plugin uninstall look@hartbrook-plugins + /plugin install look@hartbrook-plugins + ``` + +### Semver guidance + +- **Patch** (0.5.0 -> 0.5.1): bug fixes, doc-only changes, internal refactors. +- **Minor** (0.5.0 -> 0.6.0): new arguments, new skills, new output fields, anything additive. +- **Major** (0.x.0 -> 1.0.0): breaking changes to command names, argument names, or output contracts that downstream tooling parses. + +While the project is pre-1.0, breaking changes can also go in a minor bump - call them out clearly in the CHANGELOG under "### Changed" with a "Breaking:" prefix. + +## When in doubt + +- Read `CONTRIBUTING.md` for human-contributor workflow details. +- Read `README.md` for user-facing behavior. diff --git a/README.md b/README.md index 4539137..833670b 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,24 @@ To update to the latest version: /plugin install look@hartbrook-plugins ``` +## Releasing + +The marketplace tracks `main` of this repo - there are no git tags or GitHub releases. Bumping the version on `main` is what makes a new release visible to users. + +Checklist for cutting a release: + +1. Branch off `main`: `git checkout -b release/vX.Y.Z` +2. Bump version in **both** manifest files (kept in sync, enforced by `make test`): + - `src/dot-claude-plugin/plugin.json` -> `"version"` + - `.claude-plugin/marketplace.json` -> `plugins[0].version` +3. Add a `## [X.Y.Z] - YYYY-MM-DD` entry to `CHANGELOG.md` (Keep a Changelog format). +4. Run `make test`. Fix anything it flags. +5. (Recommended) `make eval` after prompt or argument-handling changes; `make integration` after orchestration or output-format changes. Both require `ANTHROPIC_API_KEY`. +6. Commit, push, open a PR against `main`. +7. After merge, users update via the [Updating](#updating) steps above. + +See [CLAUDE.md](CLAUDE.md) for semver guidance and additional project-level notes. + ## Development ```bash diff --git a/src/dot-claude-plugin/plugin.json b/src/dot-claude-plugin/plugin.json index 61ad0b7..56148bf 100644 --- a/src/dot-claude-plugin/plugin.json +++ b/src/dot-claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "look", - "version": "0.4.0", + "version": "0.5.0", "description": "Sequential code review with fresh agent contexts. Runs multiple independent review passes to catch more issues.", "author": { "name": "HartBrook" }, "repository": "https://github.com/HartBrook/lookagain", From 6b88616e91848f4becb53863c96eaff51022486c Mon Sep 17 00:00:00 2001 From: Will Pike <6687499+pike00@users.noreply.github.com> Date: Tue, 12 May 2026 15:12:40 -0500 Subject: [PATCH 2/3] chore(release): drop CLAUDE.md, inline semver guidance into README Removes the standalone CLAUDE.md added in the previous commit and folds its semver guidance into the README's Releasing section, so the release checklist and semver rules live in one place. --- CLAUDE.md | 66 ------------------------------------------------------- README.md | 8 ++++++- 2 files changed, 7 insertions(+), 67 deletions(-) delete mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index b6d4d61..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,66 +0,0 @@ -# CLAUDE.md - -Project-level instructions for Claude Code working in this repo. - -## What this is - -`lookagain` is a Claude Code plugin (published via the `hartbrook-plugins` marketplace) that runs sequential multi-pass code reviews. The main user-facing surface is the `/look:again` skill. - -## Layout - -- `src/skills/again/SKILL.md` - orchestrator prompt for `/look:again` -- `src/skills/tidy/SKILL.md` - `/look:tidy` cleanup skill -- `src/skills/lookagain-output-format/SKILL.md` - JSON output contract the reviewer subagent must follow -- `src/agents/lookagain-reviewer.md` - reviewer subagent definition -- `src/dot-claude-plugin/plugin.json` - plugin manifest (becomes `.claude-plugin/plugin.json` in the built dist) -- `.claude-plugin/marketplace.json` - marketplace manifest at repo root (what the marketplace fetches from `main`) -- `scripts/package.sh` - build script (renames `dot-*` -> `.*` and zips) -- `scripts/test.sh` - structural validation -- `evals/promptfooconfig.yaml` - behavioral evals - -## Editing rules - -- Skill prompts (`src/skills/**/SKILL.md`): use `$ARGUMENTS` (whole string) or `$ARGUMENTS[N]` (positional) only. Do not use `arguments:` frontmatter array or `$ARGUMENTS.` dot-access; neither is interpolated by Claude Code. See CONTRIBUTING.md "Writing Skill Prompts" for the full pattern. -- Every skill that uses `$ARGUMENTS` must have an `argument-hint` in frontmatter, a defaults table in the body, and a "log the resolved configuration" instruction. `make test` enforces this. -- User-triggered skills should set `disable-model-invocation: true` so Claude does not auto-fire them. - -## Tests - -- `make test` - structural validation, free, offline. Run before every commit. -- `make eval` - behavioral evals via promptfoo. Run after prompt or argument-handling changes. Needs `ANTHROPIC_API_KEY`. -- `make integration` - end-to-end review in a temp repo. Run after pipeline/output-format changes. Needs `ANTHROPIC_API_KEY`. - -## Release process - -The marketplace tracks `main` of this repo. There are no git tags or GitHub releases - bumping the version on `main` is what makes a new release visible to users. - -Checklist for cutting a release: - -1. Branch off `main`: `git checkout -b release/vX.Y.Z`. -2. Bump version in **both** manifest files (must stay in sync): - - `src/dot-claude-plugin/plugin.json` -> `"version": "X.Y.Z"` - - `.claude-plugin/marketplace.json` -> `"version": "X.Y.Z"` (inside `plugins[0]`) -3. Add a `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` under "Added"/"Changed"/"Fixed"/"Removed" using Keep a Changelog conventions. -4. Run `make test`. Fix anything it flags. -5. (Recommended for skill prompt changes) `make eval`. -6. (Recommended for orchestration/output-format changes) `make integration`. -7. Commit, push, open a PR against `main`. -8. After merge, end users update with: - ``` - /plugin marketplace update hartbrook-plugins - /plugin uninstall look@hartbrook-plugins - /plugin install look@hartbrook-plugins - ``` - -### Semver guidance - -- **Patch** (0.5.0 -> 0.5.1): bug fixes, doc-only changes, internal refactors. -- **Minor** (0.5.0 -> 0.6.0): new arguments, new skills, new output fields, anything additive. -- **Major** (0.x.0 -> 1.0.0): breaking changes to command names, argument names, or output contracts that downstream tooling parses. - -While the project is pre-1.0, breaking changes can also go in a minor bump - call them out clearly in the CHANGELOG under "### Changed" with a "Breaking:" prefix. - -## When in doubt - -- Read `CONTRIBUTING.md` for human-contributor workflow details. -- Read `README.md` for user-facing behavior. diff --git a/README.md b/README.md index 833670b..eefad3d 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,13 @@ Checklist for cutting a release: 6. Commit, push, open a PR against `main`. 7. After merge, users update via the [Updating](#updating) steps above. -See [CLAUDE.md](CLAUDE.md) for semver guidance and additional project-level notes. +### Semver guidance + +- **Patch** (0.5.0 -> 0.5.1): bug fixes, doc-only changes, internal refactors. +- **Minor** (0.5.0 -> 0.6.0): new arguments, new skills, new output fields, anything additive. +- **Major** (0.x.0 -> 1.0.0): breaking changes to command names, argument names, or output contracts that downstream tooling parses. + +While the project is pre-1.0, breaking changes can also go in a minor bump — call them out in the CHANGELOG with a "Breaking:" prefix. ## Development From 4cf2b771b195bec1bf117e4565c82b573fa9c6bb Mon Sep 17 00:00:00 2001 From: Will Pike <6687499+pike00@users.noreply.github.com> Date: Tue, 12 May 2026 15:42:11 -0500 Subject: [PATCH 3/3] Update docs to be in contributing instead of readme --- CONTRIBUTING.md | 16 ++++++++++++++-- README.md | 24 ------------------------ 2 files changed, 14 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e819e1c..d125523 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -152,6 +152,18 @@ When editing or adding skills in `src/skills/`: 5. Commit with a clear message 6. Open a pull request -## Versioning +## Releasing -Update the version in `src/dot-claude-plugin/plugin.json` when making releases. The marketplace entry in `.claude-plugin/marketplace.json` also has a `version` field — keep both in sync. The test suite (`make test`) validates that agents and skills match between the two files. +The marketplace tracks `main` of this repo - there are no git tags or GitHub releases. Bumping the version on `main` is what makes a new release visible to users. + +Checklist for cutting a release: + +1. Branch off `main`: `git checkout -b release/vX.Y.Z` +2. Bump version in **both** manifest files (kept in sync, enforced by `make test`): + - `src/dot-claude-plugin/plugin.json` -> `"version"` + - `.claude-plugin/marketplace.json` -> `plugins[0].version` +3. Add a `## [X.Y.Z] - YYYY-MM-DD` entry to `CHANGELOG.md` (Keep a Changelog format). +4. Run `make test`. Fix anything it flags. +5. (Recommended) `make eval` after prompt or argument-handling changes; `make integration` after orchestration or output-format changes. Both require `ANTHROPIC_API_KEY`. +6. Commit, push, open a PR against `main`. +7. After merge, users pick up the new version via the [Updating](README.md#updating) steps in the README. diff --git a/README.md b/README.md index eefad3d..4539137 100644 --- a/README.md +++ b/README.md @@ -150,30 +150,6 @@ To update to the latest version: /plugin install look@hartbrook-plugins ``` -## Releasing - -The marketplace tracks `main` of this repo - there are no git tags or GitHub releases. Bumping the version on `main` is what makes a new release visible to users. - -Checklist for cutting a release: - -1. Branch off `main`: `git checkout -b release/vX.Y.Z` -2. Bump version in **both** manifest files (kept in sync, enforced by `make test`): - - `src/dot-claude-plugin/plugin.json` -> `"version"` - - `.claude-plugin/marketplace.json` -> `plugins[0].version` -3. Add a `## [X.Y.Z] - YYYY-MM-DD` entry to `CHANGELOG.md` (Keep a Changelog format). -4. Run `make test`. Fix anything it flags. -5. (Recommended) `make eval` after prompt or argument-handling changes; `make integration` after orchestration or output-format changes. Both require `ANTHROPIC_API_KEY`. -6. Commit, push, open a PR against `main`. -7. After merge, users update via the [Updating](#updating) steps above. - -### Semver guidance - -- **Patch** (0.5.0 -> 0.5.1): bug fixes, doc-only changes, internal refactors. -- **Minor** (0.5.0 -> 0.6.0): new arguments, new skills, new output fields, anything additive. -- **Major** (0.x.0 -> 1.0.0): breaking changes to command names, argument names, or output contracts that downstream tooling parses. - -While the project is pre-1.0, breaking changes can also go in a minor bump — call them out in the CHANGELOG with a "Breaking:" prefix. - ## Development ```bash