diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d29f19..1961173 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,9 @@ All notable changes to this project. Format: [Keep a Changelog](https://keepacha ## Unreleased -- **fix(portability): scaffolding from Windows emitted CRLF into every generated file; `--check` crashed; two hooks assumed tools that aren't there.** Four bugs, all invisible to a Linux-only CI. **(1) CRLF output.** `Path.write_text()` opens in text mode with `newline=None`, which translates `\n` to `os.linesep` — so a Windows scaffold wrote CRLF into all 13 hooks, `claude-ctx`, `CLAUDE.md` and `settings.json` (measured: 100% CRLF, zero bare LF). Harmless *on* Windows, where Git Bash strips the CR, but the shebang carried one, and `.claude/` is meant to be committed and shared (the generated CLAUDE.md says so, and `small-team` is a shipped persona) — so a teammate's Linux/macOS clone got `bad interpreter: /usr/bin/env bash^M` on every hook. All six write sites now route through a `write_text_lf()` helper using `open(..., newline="\n")` (`Path.write_text` only gained a `newline` parameter in 3.10; the project floor is 3.8). **(2) `--check` crashed on Windows** with `UnicodeEncodeError` on the `✓` under cp1252 — the exact command CONTRIBUTING gives new contributors. Python uses UTF-8 for a real Windows console, so this bit hardest when output was piped or redirected (CI logs, `cc-configure > setup.log`, an editor terminal). Both streams are now retagged UTF-8 with `errors="replace"` where the runtime allows it. **(3) The Stop hook's report depended on an unguarded `jq -n`.** jq isn't preinstalled on macOS, Windows, or most Linux distros; without it the checks ran, the hook exited 0, and Claude never learned anything had failed — the hook's entire purpose, lost silently. It now prefers jq, falls back to python3, and as a last resort prints the report to stderr with an explicit "NOT reaching Claude" warning. **(4) The package-availability gate disabled itself on stock macOS.** It bounded each probe with GNU `timeout`, absent there; the resulting rc=127 took the "probe inconclusive" branch, so the gate stood down on the first package for every macOS user — fail-open, so no false denials, but the advertised `safety` feature simply did not work, and said nothing. It now falls back to `gtimeout`, then to an unbounded probe. **(5) `--check`'s shell-syntax gate mis-fired on Windows CI.** `shutil.which("bash")` resolves to `System32ash.exe` — the WSL launcher — on the GitHub `windows-latest` image, ahead of Git Bash. With no distro installed it exits non-zero writing *nothing* to stderr, so all 16 shipped `.sh` files were reported as `bash syntax error:` with a blank message, while the same command passed on a dev box where Git Bash wins PATH. Found only once the new matrix job ran the gate on a real Windows runner — the job earning its keep on its first run. Candidates are now validated by *executing* one (`bash -c 'exit 0'`), with Git Bash's own binary as fallback and `CC_BASH` as an override; when none works the check emits a single WARN and still passes, because a validation that could not run is not the same as one that failed. Reported paths are `as_posix()`-normalized and bash's echo of its own absolute path is stripped, so `--check` output is now byte-identical on all three platforms. **Mitigation for what the configurator can't control:** the scaffold appends a `.gitattributes` block (`*.sh text eol=lf`, `claude-ctx`, `.claude/skills/**/scripts/*`) through the same managed-block append the `.gitignore` block uses — written when absent, line-level-unioned into a stale block, never touching the user's own rules. Git cannot record the *executable* bit that way, and `core.filemode=false` (the Windows default) drops it, so the generated `CLAUDE.md` § Repo bootstrap now tells Windows committers to run `git update-index --chmod=+x claude-ctx`. New `test/portability/` fixtures cover all of it by behavior, not by grepping source: every generated file is CRLF-free and every hook shebang is clean; the `.gitattributes` block is written, idempotent and union-safe; and the two hooks are run under a PATH that hides jq, python3 and timeout. README's runtime-dependency list now names jq and the timeout fallback; the platform table reflects what CI actually exercises. The `python-uv-fastapi` example and all five persona snapshots are regenerated (`.gitattributes` is new output). +- **fix(commands): rename `/review` → `/review-branch` so it stops shadowing the bundled `/code-review`.** CC 2.1.223 made `/review` the alias of the bundled `/code-review` — Claude Code's multi-agent reviewer, including the cloud `ultra` mode. A project skill of that name wins it (verified headlessly on 2.1.241: a project skill named `review` ran for `/review`, and the same held for `plan` against the built-in `/plan`), so **every scaffolded project was silently hiding the better built-in behind this simpler single-pass skill** — overlap that turned into a real capability loss the day the alias shipped. The skill moves to `templates/commands/review-branch/` with `name: review-branch`, and its description now positions it honestly ("a quick single-pass review; Claude Code's bundled `/code-review` is the deeper multi-agent one"). Both are reachable again. Updated across `config_schema.py`, `configure.py`'s pattern-integration map, `templates/INDEX.md`, the `/investigate` and `/plan-eng-review` cross-references, docs 02/03/05/09/10/11, README, and the example project. **Migration:** the configurator has no mechanism to delete a file it previously wrote, so an upgraded project keeps the old `.claude/skills/review/` alongside the new one — and the stale copy still shadows the alias. New `/verify-setup` **check 13** detects exactly that pair and tells the user to `rm -rf .claude/skills/review`. `/plan` is left alone deliberately: it shadows a built-in *command* rather than a bundled skill, and plan mode stays reachable via Shift+Tab, so it's a name clash rather than a lost capability — README now says so and points at the rename if you'd rather keep the shortcut. + +- **fix(portability): scaffolding from Windows emitted CRLF into every generated file; `--check` crashed; two hooks assumed tools that aren't there.** Four bugs, all invisible to a Linux-only CI. **(1) CRLF output.** `Path.write_text()` opens in text mode with `newline=None`, which translates `\n` to `os.linesep` — so a Windows scaffold wrote CRLF into all 13 hooks, `claude-ctx`, `CLAUDE.md` and `settings.json` (measured: 100% CRLF, zero bare LF). Harmless *on* Windows, where Git Bash strips the CR, but the shebang carried one, and `.claude/` is meant to be committed and shared (the generated CLAUDE.md says so, and `small-team` is a shipped persona) — so a teammate's Linux/macOS clone got `bad interpreter: /usr/bin/env bash^M` on every hook. All six write sites now route through a `write_text_lf()` helper using `open(..., newline="\n")` (`Path.write_text` only gained a `newline` parameter in 3.10; the project floor is 3.8). **(2) `--check` crashed on Windows** with `UnicodeEncodeError` on the `✓` under cp1252 — the exact command CONTRIBUTING gives new contributors. Python uses UTF-8 for a real Windows console, so this bit hardest when output was piped or redirected (CI logs, `cc-configure > setup.log`, an editor terminal). Both streams are now retagged UTF-8 with `errors="replace"` where the runtime allows it. **(3) The Stop hook's report depended on an unguarded `jq -n`.** jq isn't preinstalled on macOS, Windows, or most Linux distros; without it the checks ran, the hook exited 0, and Claude never learned anything had failed — the hook's entire purpose, lost silently. It now prefers jq, falls back to python3, and as a last resort prints the report to stderr with an explicit "NOT reaching Claude" warning. **(4) The package-availability gate disabled itself on stock macOS.** It bounded each probe with GNU `timeout`, absent there; the resulting rc=127 took the "probe inconclusive" branch, so the gate stood down on the first package for every macOS user — fail-open, so no false denials, but the advertised `safety` feature simply did not work, and said nothing. It now falls back to `gtimeout`, then to an unbounded probe. **Mitigation for what the configurator can't control:** the scaffold appends a `.gitattributes` block (`*.sh text eol=lf`, `claude-ctx`, `.claude/skills/**/scripts/*`) through the same managed-block append the `.gitignore` block uses — written when absent, line-level-unioned into a stale block, never touching the user's own rules. Git cannot record the *executable* bit that way, and `core.filemode=false` (the Windows default) drops it, so the generated `CLAUDE.md` § Repo bootstrap now tells Windows committers to run `git update-index --chmod=+x claude-ctx`. New `test/portability/` fixtures cover all of it by behavior, not by grepping source: every generated file is CRLF-free and every hook shebang is clean; the `.gitattributes` block is written, idempotent and union-safe; and the two hooks are run under a PATH that hides jq, python3 and timeout. README's runtime-dependency list now names jq and the timeout fallback; the platform table reflects what CI actually exercises. The `python-uv-fastapi` example and all five persona snapshots are regenerated (`.gitattributes` is new output). - **fix(install): the `ln -sf` shortcut silently froze on Windows; PATH-independent shim, honest prerequisites.** Under Git Bash/MSYS, `ln -s` **copies** unless `MSYS=winsymlinks:nativestrict` is set *and* the user has Developer Mode or admin — so `~/.local/bin/cc-configure` became a snapshot of configure.py taken on install day. `git -C ~/.cc-configurator pull` updated the clone while the command kept running the old copy, with nothing to indicate it. The installer now verifies the link actually resolved (`[ -L ]`) and otherwise writes a two-line `exec python3 /configure.py "$@"` shim, which tracks the clone on every platform; both checks live in the `if` condition, because under `set -e` a trailing `[ -L … ] && link_ok=1` in a then-block would abort the installer on precisely the platform the fallback exists for. Also: `git` is now checked up front (it was used before the first guard), the missing-python3 hint is OS-aware instead of always saying `apt install python3`, and the closing usage banner no longer advertises `--preset aggressive` and the legacy `commands-core` / `token-efficiency-pro` module IDs — both deprecated and slated for removal in v3.0. diff --git a/README.md b/README.md index 74e2c3c..56d04c3 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ There are 11 modules; legacy IDs (`commands-core`, `agents`, `token-efficiency-p | **safety** | PreToolUse hooks (block dangerous bash + scan Write/Edit for secrets + gate `apt\|brew\|dnf\|yum\|pacman\|apk install` for packages not in any configured repo, with structured denial listing available siblings + detected installed version); `permissions.disableBypassPermissionsMode: "disable"` hard-blocks `--dangerously-skip-permissions`. Sub-flags: `lockdown` (sets `DISABLE_UPDATES=1` — blocks autoupdates AND manual `claude update`; for air-gapped / enterprise environments); `slop_scan` (PostToolUse hook on Write/Edit/NotebookEdit flagging filler / marketing-voice / hedging / em-dash patterns; `slop_scan_action=warn\|block`, `slop_scan_density` and `slop_scan_imports` opt-in). All non-`custom` personas pre-set `slop_scan=true` action=warn. | | **git-workflow** | PostToolUse formatter on Write/Edit, Stop hook running typecheck / lint / tests. | | **token-efficiency** | Path-scoped `.claude/rules/` starters + PreCompact snapshot hook. `tier` flag: `basic` (default) ships discipline rules + snapshot only; `pro` adds bash-output truncation hook + always-loaded discipline rules. | -| **commands** | Slash commands + agents + microbits. `subset` flag (linear ordering: `curated ⊂ full ⊂ rigorous`): **`curated`** = 3 essential skills (`/plan`, `/commit`, `/verify-setup`) + the `code-reviewer` agent. **`full`** (default) = 9 workflow skills (adds `/review`, `/ship`, `/sync-docs`, `/check-context`, `/session-retro`, `/retrofit`) + 4 agents (`code-reviewer`, `test-runner`, `doc-writer`, `security-auditor`) + 4 discipline microbits (`/freeze`, `/unfreeze`, `/guard`, `/careful`) + the `microbit-enforcer.sh` PreToolUse hook. **`rigorous`** = `full` + `/investigate` + `/plan-eng-review`, the rigor skills that embed `templates/commands/_patterns/` cross-cutting blocks (confidence gate, independent verification, no-fix-without-investigation, AI-slop detection). `/review` and `/plan` share their names with Claude Code built-ins (the `/review` alias of the bundled `/code-review` since CC 2.1.223, and the `/plan` plan-mode shortcut); a project skill wins by name (verified on CC 2.1.241), so reach the built-in multi-agent review with `/code-review` and plan mode with Shift+Tab. The `security-auditor` frontmatter wires Sonatype's dependency-management MCP (`https://mcp.guide.sonatype.com/mcp`) scoped to that agent — active only when it runs, so ~0 baseline context cost. Set `SONATYPE_TOKEN` env var to enable ([generate a token](https://guide.sonatype.com/settings/tokens)). | +| **commands** | Slash commands + agents + microbits. `subset` flag (linear ordering: `curated ⊂ full ⊂ rigorous`): **`curated`** = 3 essential skills (`/plan`, `/commit`, `/verify-setup`) + the `code-reviewer` agent. **`full`** (default) = 9 workflow skills (adds `/review-branch`, `/ship`, `/sync-docs`, `/check-context`, `/session-retro`, `/retrofit`) + 4 agents (`code-reviewer`, `test-runner`, `doc-writer`, `security-auditor`) + 4 discipline microbits (`/freeze`, `/unfreeze`, `/guard`, `/careful`) + the `microbit-enforcer.sh` PreToolUse hook. **`rigorous`** = `full` + `/investigate` + `/plan-eng-review`, the rigor skills that embed `templates/commands/_patterns/` cross-cutting blocks (confidence gate, independent verification, no-fix-without-investigation, AI-slop detection). **Naming note:** a project skill wins its name against Claude Code's built-ins (verified on CC 2.1.241). `/review-branch` is deliberately *not* called `review`, because CC 2.1.223 made `/review` the alias of the bundled `/code-review` and taking that name would hide Claude Code's multi-agent reviewer. `/plan` does still shadow the built-in plan-mode shortcut — plan mode remains reachable with Shift+Tab, so this is a name clash rather than a lost capability; rename the skill if you'd rather keep the shortcut. The `security-auditor` frontmatter wires Sonatype's dependency-management MCP (`https://mcp.guide.sonatype.com/mcp`) scoped to that agent — active only when it runs, so ~0 baseline context cost. Set `SONATYPE_TOKEN` env var to enable ([generate a token](https://guide.sonatype.com/settings/tokens)). | | **mcp** | `.mcp.json` generated from selected servers, plus **per-task profiles** (`.mcp.research.json`, `.mcp.frontend.json`, `.mcp.minimal.json`) and an executable `./claude-ctx` wrapper that launches Claude with `--mcp-config --strict-mcp-config` — drops a bloated 4-MCP baseline from ~49% context to under 5%. | | **multi-agent** | Path-scoped `multi-agent-guardrails.md` (5-scenario "when not to parallel" list), `/merge-worktrees` skill, `/infinite` skill, `parallel-generator` subagent. | | **github-actions** | `.github/workflows/claude.yml` pinned to `anthropics/claude-code-action@v1`. Triggers on `@claude` mentions in issues, PR comments, and PR reviews. | diff --git a/config_schema.py b/config_schema.py index 68f8bb8..c5a44e5 100644 --- a/config_schema.py +++ b/config_schema.py @@ -111,10 +111,10 @@ { "id": "commands", "title": "Slash commands + subagents", - "description": "Bundled commands (plan/review/commit/ship/sync-docs/check-context/session-retro/verify-setup/retrofit) + 4 subagents (code-reviewer/test-runner/doc-writer/security-auditor).", + "description": "Bundled commands (plan/review-branch/commit/ship/sync-docs/check-context/session-retro/verify-setup/retrofit) + 4 subagents (code-reviewer/test-runner/doc-writer/security-auditor).", "paths": [ "commands/plan/SKILL.md", - "commands/review/SKILL.md", + "commands/review-branch/SKILL.md", "commands/commit/SKILL.md", "commands/ship/SKILL.md", "commands/sync-docs/SKILL.md", diff --git a/configure.py b/configure.py index 3ed407e..429af08 100755 --- a/configure.py +++ b/configure.py @@ -896,7 +896,7 @@ def warn(source, msg): "_patterns/confidence-gate.md", "_patterns/independent-verification.md", ], - "commands/review/SKILL.md": [ + "commands/review-branch/SKILL.md": [ "_patterns/confidence-gate.md", "_patterns/independent-verification.md", "_patterns/ai-slop-detection.md", diff --git a/docs/02-git-workflow.md b/docs/02-git-workflow.md index 0b65f79..a5a0a70 100644 --- a/docs/02-git-workflow.md +++ b/docs/02-git-workflow.md @@ -8,7 +8,7 @@ Every change follows this shape: 2. **Branch** — `git checkout -b feat/` off main. 3. **Small diff** — one logical change at a time. If the diff grows past ~200 LOC, split. 4. **Tests** — every new behavior gets a test in the same branch. -5. **Review** — `/review` or let `code-reviewer` subagent run. Address critical issues. +5. **Review** — `/review-branch` or let `code-reviewer` subagent run. Address critical issues. 6. **Ship** — `/ship` runs format → lint → typecheck → test → commit → push. ## Branch naming @@ -133,7 +133,7 @@ Rewind (`Esc Esc` in Claude Code) and `git reflog` are your safety net. You don' 1. `claude` from the repo root. 2. Describe the task. Claude drafts a plan (via `/plan` or plan mode). 3. Confirm or adjust, then let it edit. -4. `/review` → fix what matters. +4. `/review-branch` → fix what matters. 5. `/ship` → commits and pushes. 6. Open PR manually or with `gh pr create`. Merge. diff --git a/docs/03-commands-and-hooks.md b/docs/03-commands-and-hooks.md index 41e5ffe..a7056c0 100644 --- a/docs/03-commands-and-hooks.md +++ b/docs/03-commands-and-hooks.md @@ -45,12 +45,12 @@ Frontmatter fields worth knowing: Inline: `` !`git diff --staged` `` — runs at skill-expansion time, output replaces the placeholder before Claude sees the prompt. Multi-line: fenced block ```` ```! ````. -Great for injecting live repo state into the prompt. The `/review` and `/commit` skills in the template library use this. +Great for injecting live repo state into the prompt. The `/review-branch` and `/commit` skills in the template library use this. ### Starter kit - `/plan` — forces a structured plan before edits. Shadows Claude Code's built-in `/plan` (the plan-mode shortcut) — a project skill wins by name; Shift+Tab still enters plan mode. -- `/review` — code review against main via the `code-reviewer` agent. Shadows the bundled `/review` alias that CC 2.1.223 added for `/code-review` (verified on 2.1.241) — type `/code-review` for the built-in multi-agent review. +- `/review-branch` — code review against main via the `code-reviewer` agent. Named `review-branch`, not `review`, on purpose: CC 2.1.223 made `/review` the alias of the bundled `/code-review`, and a project skill of that name wins it (verified on 2.1.241), which would hide Claude Code's multi-agent reviewer behind this simpler one. Both are available now — `/code-review` for the deep pass, `/review-branch` for the quick one. - `/commit` — Conventional Commits from staged diff. - `/ship` — full pre-push gauntlet. - `/sync-docs` — update `CLAUDE.md` / rules from recent work. diff --git a/docs/05-safety-permissions.md b/docs/05-safety-permissions.md index 0711ddb..58dbd2e 100644 --- a/docs/05-safety-permissions.md +++ b/docs/05-safety-permissions.md @@ -108,7 +108,7 @@ Writes a summary of the session to `.claude/logs/` before compression happens. R Automated review is the last line. ### At turn-end -The `code-reviewer` subagent runs against `git diff` or `git diff --merge-base main`. Called explicitly via `/review` or auto-invoked when Claude writes code with "use proactively" description matching. +The `code-reviewer` subagent runs against `git diff` or `git diff --merge-base main`. Called explicitly via `/review-branch` or auto-invoked when Claude writes code with "use proactively" description matching. ### At commit-time The `/commit` skill forces a Conventional Commit message summarizing the change, which forces the model to think about whether the diff actually does what it thinks. diff --git a/docs/09-retrofit-guide.md b/docs/09-retrofit-guide.md index 76f8c02..6d30ec0 100644 --- a/docs/09-retrofit-guide.md +++ b/docs/09-retrofit-guide.md @@ -88,7 +88,7 @@ Two paths: **Manual.** Diff each pair from the report and decide: ```bash -diff -u .claude/skills/review/SKILL.md .claude-retrofit/incoming/.claude/skills/review/SKILL.md +diff -u .claude/skills/review-branch/SKILL.md .claude-retrofit/incoming/.claude/skills/review-branch/SKILL.md ``` For each, decide: keep yours (delete the staged), replace yours with ours (`mv`), merge sections (edit by hand), or install ours alongside (move to `-cc/SKILL.md`). diff --git a/docs/10-plugin-ecosystem.md b/docs/10-plugin-ecosystem.md index 6ab132e..9c97080 100644 --- a/docs/10-plugin-ecosystem.md +++ b/docs/10-plugin-ecosystem.md @@ -21,7 +21,7 @@ Some configurator-shipped surfaces have direct or near-direct plugin equivalents | Configurator | Plugin equivalent | Notes | |---|---|---| -| `commands-core` skills (`/plan`, `/review`, `/commit`, `/ship`) | `feature-dev` plugin (3 agents + `/feature-dev` command) and `commit-commands` plugin (`/commit`, `/commit-push-pr`, `/clean_gone`) | Plugins are Anthropic-maintained and richer; the configurator's are simpler defaults you can edit. Either-or, not both. | +| `commands-core` skills (`/plan`, `/review-branch`, `/commit`, `/ship`) | `feature-dev` plugin (3 agents + `/feature-dev` command) and `commit-commands` plugin (`/commit`, `/commit-push-pr`, `/clean_gone`) | Plugins are Anthropic-maintained and richer; the configurator's are simpler defaults you can edit. Either-or, not both. | | `code-reviewer` subagent | `feature-dev`'s `code-reviewer` agent (with confidence-based filtering) | Plugin version is more sophisticated; ours is a simpler baseline. | | `/sync-docs`, `/session-retro` | `claude-md-management` plugin (`claude-md-improver` skill + `/revise-claude-md`) | Different focus: ours captures session learnings; theirs audits any CLAUDE.md against quality criteria. Complementary; both can coexist. | | `safety` hooks (`block-dangerous-bash.sh`, `scan-secrets.sh`) | `security-guidance` plugin + `hookify` plugin | Ours are static bash scripts; the plugin path lets you author hooks via markdown rules. | @@ -91,7 +91,7 @@ The configurator ships a `discipline-skills` module — a curated 7-skill subset **Why ship a fork instead of just recommending the upstream plugin:** - **~930 tokens saved per session.** Full superpowers injects ~1,200 tokens at SessionStart via `using-superpowers` plus ~270 tokens of skill descriptions for 14 skills. The configurator's bootstrap is ~400 tokens and we ship 7 skill descriptions, totaling ~540 — a ~63% reduction in fixed session-overhead for these capabilities. -- **Curation control.** The configurator picks which 7 skills earn the context cost. The other 7 upstream skills (`systematic-debugging`, `test-driven-development`, `dispatching-parallel-agents`, `requesting-code-review`, `receiving-code-review`, `writing-skills`, `using-superpowers`) overlap configurator-shipped equivalents (`/investigate`, `multi-agent-guardrails.md`, `/review`, `code-reviewer` agent) or are too meta for the default kit. +- **Curation control.** The configurator picks which 7 skills earn the context cost. The other 7 upstream skills (`systematic-debugging`, `test-driven-development`, `dispatching-parallel-agents`, `requesting-code-review`, `receiving-code-review`, `writing-skills`, `using-superpowers`) overlap configurator-shipped equivalents (`/investigate`, `multi-agent-guardrails.md`, `/review-branch`, `code-reviewer` agent) or are too meta for the default kit. - **Rugpull immunity.** Upstream v5.1.0 (2026-04-30) removed three slash commands (`/brainstorm`, `/write-plan`, `/execute-plan`) — that broke configurator references and required a cleanup PR. A forked-snapshot module stays stable until we choose to sync. - **Plugin-skill namespacing means no conflict.** Per `code.claude.com/docs/en/skills`: *"Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels."* If a user installs both this module and the upstream plugin, the configurator's bootstrap auto-suppresses (detects `~/.claude/plugins/cache/claude-plugins-official/superpowers/`) and the two coexist. `/verify-setup` Check #12 flags the duplication so the user can pick one. diff --git a/docs/11-getting-started.md b/docs/11-getting-started.md index bf38503..d123fe0 100644 --- a/docs/11-getting-started.md +++ b/docs/11-getting-started.md @@ -140,8 +140,8 @@ The `/retrofit` skill (shipped in `commands-core`) walks `.claude-retrofit/REPOR For each pair in the report: ```bash -diff -u .claude/skills/review/SKILL.md \ - .claude-retrofit/incoming/.claude/skills/review/SKILL.md +diff -u .claude/skills/review-branch/SKILL.md \ + .claude-retrofit/incoming/.claude/skills/review-branch/SKILL.md ``` Decide per file: keep yours (delete the staged), replace yours with ours (`mv`), merge sections (edit by hand), or install ours alongside (`mv` to `-cc/SKILL.md`). @@ -167,7 +167,7 @@ Optional: install `claude-md-management` and run its `/revise-claude-md` for an Once scaffolded, the configurator's job is done. Day-to-day: - `/plan` (configurator) or the `brainstorming` skill (`superpowers`) — scope the next change -- `/review` (configurator) or `feature-dev` plugin's `code-reviewer` agent — review a diff +- `/review-branch` (configurator) or `feature-dev` plugin's `code-reviewer` agent — review a diff - `/ship` (configurator) or `commit-commands` plugin's `/commit-push-pr` — push the change - `/check-context` (configurator) — look at where context is going if sessions feel slow - `/verify-setup` (configurator) — audit the `.claude/` shape against best practices diff --git a/examples/persona-library-author/expected-tree.txt b/examples/persona-library-author/expected-tree.txt index a15b59a..c5d89de 100644 --- a/examples/persona-library-author/expected-tree.txt +++ b/examples/persona-library-author/expected-tree.txt @@ -22,7 +22,7 @@ ./.claude/skills/guard/SKILL.md ./.claude/skills/plan/SKILL.md ./.claude/skills/retrofit/SKILL.md -./.claude/skills/review/SKILL.md +./.claude/skills/review-branch/SKILL.md ./.claude/skills/session-retro/SKILL.md ./.claude/skills/ship/SKILL.md ./.claude/skills/sync-docs/SKILL.md diff --git a/examples/persona-small-team/expected-tree.txt b/examples/persona-small-team/expected-tree.txt index f5cf1a4..fd6713f 100644 --- a/examples/persona-small-team/expected-tree.txt +++ b/examples/persona-small-team/expected-tree.txt @@ -44,7 +44,7 @@ ./.claude/skills/plan-eng-review/SKILL.md ./.claude/skills/plan/SKILL.md ./.claude/skills/retrofit/SKILL.md -./.claude/skills/review/SKILL.md +./.claude/skills/review-branch/SKILL.md ./.claude/skills/session-retro/SKILL.md ./.claude/skills/ship/SKILL.md ./.claude/skills/subagent-driven-development/SKILL.md diff --git a/examples/persona-solo-experienced/expected-tree.txt b/examples/persona-solo-experienced/expected-tree.txt index 34ffab7..c3de159 100644 --- a/examples/persona-solo-experienced/expected-tree.txt +++ b/examples/persona-solo-experienced/expected-tree.txt @@ -40,7 +40,7 @@ ./.claude/skills/plan-eng-review/SKILL.md ./.claude/skills/plan/SKILL.md ./.claude/skills/retrofit/SKILL.md -./.claude/skills/review/SKILL.md +./.claude/skills/review-branch/SKILL.md ./.claude/skills/session-retro/SKILL.md ./.claude/skills/ship/SKILL.md ./.claude/skills/subagent-driven-development/SKILL.md diff --git a/examples/python-uv-fastapi/.claude/.cc-manifest.json b/examples/python-uv-fastapi/.claude/.cc-manifest.json index 201a496..1f4b20b 100644 --- a/examples/python-uv-fastapi/.claude/.cc-manifest.json +++ b/examples/python-uv-fastapi/.claude/.cc-manifest.json @@ -1,8 +1,8 @@ { "manifest_version": 2, - "written_at": "2026-08-24T20:39:12Z", + "written_at": "2026-08-25T13:35:25Z", "written_by": "cc-configure 2.7.0", - "written_by_sha": "9380084", + "written_by_sha": "62b6afb", "mcp_servers": [], "stack_manifests": [], "check_commands": { diff --git a/examples/python-uv-fastapi/.claude/skills/review/SKILL.md b/examples/python-uv-fastapi/.claude/skills/review-branch/SKILL.md similarity index 93% rename from examples/python-uv-fastapi/.claude/skills/review/SKILL.md rename to examples/python-uv-fastapi/.claude/skills/review-branch/SKILL.md index ea97059..ac0fe3e 100644 --- a/examples/python-uv-fastapi/.claude/skills/review/SKILL.md +++ b/examples/python-uv-fastapi/.claude/skills/review-branch/SKILL.md @@ -1,6 +1,6 @@ --- -name: review -description: Code-review the current branch's changes against main with the code-reviewer agent. Use before committing or pushing. Distinct from Claude Code's built-in /code-review. +name: review-branch +description: Code-review the current branch's changes against main with the code-reviewer agent. Use before committing or pushing. A quick single-pass review; Claude Code's bundled /code-review is the deeper multi-agent one. argument-hint: "[optional focus area]" allowed-tools: Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git status) context: fork @@ -84,4 +84,4 @@ For each requirement stated in the PR/commit message, verify the change actually ### When you find a bug -**Don't fix in place.** Note "Run /investigate before proposing a fix" in the report. The Iron Law (see `/investigate`) says no fix without investigation; `/review`'s job is to flag, not to debug. +**Don't fix in place.** Note "Run /investigate before proposing a fix" in the report. The Iron Law (see `/investigate`) says no fix without investigation; `/review-branch`'s job is to flag, not to debug. diff --git a/examples/python-uv-fastapi/.claude/skills/verify-setup/SKILL.md b/examples/python-uv-fastapi/.claude/skills/verify-setup/SKILL.md index ec71c70..296f83c 100644 --- a/examples/python-uv-fastapi/.claude/skills/verify-setup/SKILL.md +++ b/examples/python-uv-fastapi/.claude/skills/verify-setup/SKILL.md @@ -140,6 +140,14 @@ Audit the current project's `.claude/` directory. Produce a checklist report. Do - **Only upstream superpowers:** `[ - ] Discipline skills: upstream superpowers plugin in use (configurator's module not installed).` - **Both installed:** `[ ⚠ ] Discipline skills: BOTH installed — your /skills menu has 7 forked skills + 14 upstream skills with the same names. The configurator's SessionStart bootstrap auto-suppresses, but skill invocations may resolve to either copy depending on namespace.` Suggest: pick one — either `cc-configure --retrofit` without `discipline-skills` to drop the fork, or `/plugin uninstall superpowers` to drop the upstream. +### 13. Superseded `/review` skill + +- Skip unless BOTH `.claude/skills/review/SKILL.md` and `.claude/skills/review-branch/SKILL.md` exist. +- Configurator releases before this rename shipped the skill as `review`. Claude Code 2.1.223 made `/review` the alias of the bundled `/code-review`, and a project skill of that name wins it — so the leftover directory hides Claude Code's multi-agent reviewer. The configurator has no mechanism to delete a file it previously wrote, so an upgraded project keeps both. +- **Both present:** `[ ⚠ ] Superseded skill: .claude/skills/review/ is left over from an older scaffold and shadows the bundled /review (alias of /code-review). The replacement is .claude/skills/review-branch/. Delete the old directory: rm -rf .claude/skills/review` +- **Only `review-branch/`:** `[ ✓ ] Skills: no superseded /review shadow.` +- Neither, or only `review/` (project predates the rename and hasn't been re-scaffolded) → `[ - ]` skipped. + ## Output format ``` diff --git a/examples/python-uv-fastapi/EXAMPLE_README.md b/examples/python-uv-fastapi/EXAMPLE_README.md index fdae8a3..9d6db31 100644 --- a/examples/python-uv-fastapi/EXAMPLE_README.md +++ b/examples/python-uv-fastapi/EXAMPLE_README.md @@ -31,7 +31,7 @@ The stack preset automatically filled the package manager / test runner / format - **[`CLAUDE.md`](CLAUDE.md)** — project memory. Note the `Commands` section is pre-filled with `uv sync` / `uv run pytest` / etc. rather than the default `pnpm` versions. Also contains the "Working with Claude" collaboration section (task classification, slot-machine style, commit-as-you-go, spec-driven restart). - **[`.claude/settings.json`](.claude/settings.json)** — `"model": "fable"` plus permissions (`allow` / `ask` / `deny`) skewed toward Python tooling: `pytest`, `ruff`, no `pnpm`/`tsc`. Hooks wired for PreToolUse (block-dangerous-bash, check-package-availability, scan-secrets, microbit-enforcer), PostToolUse (format-on-write), Stop (stop-run-checks), PostToolUse on Bash (truncate-bash-output). `permissions.disableBypassPermissionsMode: "disable"` ships via the safety module. - **[`.claude/rules/`](.claude/rules/)** — path-scoped rules (`frontend.md`, `backend.md`, `tests.md`) auto-load only when Claude is working with files matching their `paths:` glob. Only ~200 tokens load on a typical session instead of the whole ruleset. -- **[`.claude/skills/`](.claude/skills/)** — thirteen skills: nine workflow commands (`/plan`, `/review`, `/commit`, `/ship`, `/sync-docs`, `/check-context`, `/session-retro`, `/verify-setup`, `/retrofit`) plus the four micro-behavior toggles (`/careful`, `/freeze`, `/guard`, `/unfreeze`) enforced by `microbit-enforcer.sh`. +- **[`.claude/skills/`](.claude/skills/)** — thirteen skills: nine workflow commands (`/plan`, `/review-branch`, `/commit`, `/ship`, `/sync-docs`, `/check-context`, `/session-retro`, `/verify-setup`, `/retrofit`) plus the four micro-behavior toggles (`/careful`, `/freeze`, `/guard`, `/unfreeze`) enforced by `microbit-enforcer.sh`. - **[`.claude/agents/`](.claude/agents/)** — four specialists. `security-auditor.md` has Sonatype's dependency-management MCP wired via agent frontmatter — scoped to that agent only, so zero context cost when idle. Requires `SONATYPE_TOKEN` env var to activate. It deliberately pins `model: opus` (Fable 5's cybersecurity classifier would reroute security-review sessions to Opus anyway); `test-runner.md` rides the `fable` default era as `model: fable`. - **[`.claude/hooks/`](.claude/hooks/)** — eight shell scripts plus a shared `_lib/`, all `.sh` native (no heavy-interpreter overhead). `scan-secrets.sh` and `block-dangerous-bash.sh` are the main PreToolUse guards; `stop-run-checks.sh` runs typecheck + lint + tests at the end of each turn (and skips while background tasks are in flight, CC 2.1.145+). - **[`.claude/.cc-manifest.json`](.claude/.cc-manifest.json)** — the drift-monitor manifest (configurator v2.5.0+): records what was scaffolded, by which configurator version/SHA, so `cc-configure --whats-new` and the drift check can compare. diff --git a/templates/INDEX.md b/templates/INDEX.md index 351d4aa..2163878 100644 --- a/templates/INDEX.md +++ b/templates/INDEX.md @@ -29,7 +29,7 @@ Every module produces one or more drop-in files for a new Claude Code project. T ## Slash commands (skills) - `commands/plan/SKILL.md` → `.claude/skills/plan/SKILL.md` -- `commands/review/SKILL.md` → `.claude/skills/review/SKILL.md` +- `commands/review-branch/SKILL.md` → `.claude/skills/review-branch/SKILL.md` - `commands/commit/SKILL.md` → `.claude/skills/commit/SKILL.md` - `commands/ship/SKILL.md` → `.claude/skills/ship/SKILL.md` - `commands/sync-docs/SKILL.md` → `.claude/skills/sync-docs/SKILL.md` diff --git a/templates/commands/investigate/SKILL.md b/templates/commands/investigate/SKILL.md index e3aa4d4..0658d61 100644 --- a/templates/commands/investigate/SKILL.md +++ b/templates/commands/investigate/SKILL.md @@ -91,7 +91,7 @@ fourth fix without re-investigating. - A findings doc at `.claude/investigations/-.md` - A terse chat summary: "Root cause: . Proposed fix: (confidence: X/10)." - **No code change is made by this skill itself** — it stops at the - proposed-fix step. The user (or `/review`/`/plan`) takes it from + proposed-fix step. The user (or `/review-branch`/`/plan`) takes it from there. ## Anti-patterns this skill prevents @@ -107,7 +107,7 @@ fourth fix without re-investigating. - **/plan** authors a plan; this skill investigates a bug. Different modes. -- **/review** flags issues but does not investigate them — when - /review surfaces a bug, the right next step is `/investigate`. +- **/review-branch** flags issues but does not investigate them — when + /review-branch surfaces a bug, the right next step is `/investigate`. - **/plan-eng-review** validates a plan; this skill validates a bug report. Both apply confidence gates and independent verification. diff --git a/templates/commands/plan-eng-review/SKILL.md b/templates/commands/plan-eng-review/SKILL.md index 15837a5..e9aa372 100644 --- a/templates/commands/plan-eng-review/SKILL.md +++ b/templates/commands/plan-eng-review/SKILL.md @@ -131,4 +131,4 @@ different angle; if the issue doesn't survive double-check, drop it. - **/investigate** is for bugs in code; this skill is for issues in plans. Both share the confidence-gate + independent-verification patterns. -- **/review** is post-code review; this skill is pre-code review. +- **/review-branch** is post-code review; this skill is pre-code review. diff --git a/templates/commands/review/SKILL.md b/templates/commands/review-branch/SKILL.md similarity index 93% rename from templates/commands/review/SKILL.md rename to templates/commands/review-branch/SKILL.md index ea97059..ac0fe3e 100644 --- a/templates/commands/review/SKILL.md +++ b/templates/commands/review-branch/SKILL.md @@ -1,6 +1,6 @@ --- -name: review -description: Code-review the current branch's changes against main with the code-reviewer agent. Use before committing or pushing. Distinct from Claude Code's built-in /code-review. +name: review-branch +description: Code-review the current branch's changes against main with the code-reviewer agent. Use before committing or pushing. A quick single-pass review; Claude Code's bundled /code-review is the deeper multi-agent one. argument-hint: "[optional focus area]" allowed-tools: Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git status) context: fork @@ -84,4 +84,4 @@ For each requirement stated in the PR/commit message, verify the change actually ### When you find a bug -**Don't fix in place.** Note "Run /investigate before proposing a fix" in the report. The Iron Law (see `/investigate`) says no fix without investigation; `/review`'s job is to flag, not to debug. +**Don't fix in place.** Note "Run /investigate before proposing a fix" in the report. The Iron Law (see `/investigate`) says no fix without investigation; `/review-branch`'s job is to flag, not to debug. diff --git a/templates/commands/verify-setup/SKILL.md b/templates/commands/verify-setup/SKILL.md index c8f46a4..16c5f5e 100644 --- a/templates/commands/verify-setup/SKILL.md +++ b/templates/commands/verify-setup/SKILL.md @@ -139,6 +139,14 @@ Audit the current project's `.claude/` directory. Produce a checklist report. Do - **Only upstream superpowers:** `[ - ] Discipline skills: upstream superpowers plugin in use (configurator's module not installed).` - **Both installed:** `[ ⚠ ] Discipline skills: BOTH installed — your /skills menu has 7 forked skills + 14 upstream skills with the same names. The configurator's SessionStart bootstrap auto-suppresses, but skill invocations may resolve to either copy depending on namespace.` Suggest: pick one — either `cc-configure --retrofit` without `discipline-skills` to drop the fork, or `/plugin uninstall superpowers` to drop the upstream. +### 13. Superseded `/review` skill + +- Skip unless BOTH `.claude/skills/review/SKILL.md` and `.claude/skills/review-branch/SKILL.md` exist. +- Configurator releases before this rename shipped the skill as `review`. Claude Code 2.1.223 made `/review` the alias of the bundled `/code-review`, and a project skill of that name wins it — so the leftover directory hides Claude Code's multi-agent reviewer. The configurator has no mechanism to delete a file it previously wrote, so an upgraded project keeps both. +- **Both present:** `[ ⚠ ] Superseded skill: .claude/skills/review/ is left over from an older scaffold and shadows the bundled /review (alias of /code-review). The replacement is .claude/skills/review-branch/. Delete the old directory: rm -rf .claude/skills/review` +- **Only `review-branch/`:** `[ ✓ ] Skills: no superseded /review shadow.` +- Neither, or only `review/` (project predates the rename and hasn't been re-scaffolded) → `[ - ]` skipped. + ## Output format ```