V4.2 closes the gaps surfaced by /insights session analysis: multi-session REVISE cycles, wrong-branch reports, context exhaustion mid-handoff, unreviewed fleet merges, and squad-self-reviewing meta-work. Five new commands extend the lifecycle without replacing it — each composes with the existing squad persistent state (.review-squad/<project>/) and uses the same implement-agent dispatch pattern. The guiding rule: don’t add manual steps to close the loop — automate the loop and keep the gates.
-
/handoff — structured session-state snapshot
Captures branch, PR, last commit, this-session-accomplished, pending blockers from latest review verdict, validation status (typecheck/lint), and a single concrete next action. Writes to .claude/handoff.md as a rolling overwrite. Auto-invoked by /review on REVISE or BLOCK when context is constrained or the blocker list is substantial. Ensures .claude/handoff.md is gitignored. Enforces verb-leading next-action language — vague output is a signal the session state wasn’t clear.
-
/review-auto — closed-loop auto-fix cycle
Runs /review, classifies findings by tier (NIT / MUST-FIX-SAFE / MUST-FIX-RISKY / BLOCKER) AND by source reviewer, dispatches the matching squad implement agent per finding (FC-flagged → father-christmas-implement, Stevey-flagged → stevey-boy-choi-implement, etc.), validates via typecheck + lint with timeout guards, commits auto-fixes as chore(auto-fix): round N, re-runs /review. Iteration cap 2 (max 3 via --max-iterations). Hard safeguards: never touches migrations, secrets, package.json dependencies; Jared-flagged items always surface, never auto-apply — security-adjacent safe is an oxymoron. Agent pre-check at Step 1.5 verifies the four expected implement agents exist; missing agents prompt for user-picked replacements or skip. Appends a round-N entry to review-history.md so /ship’s gate reads the post-auto-fix verdict.
-
/fleet — parallel worktree orchestration
Decomposes a phased markdown spec (## Phase N: <title> headers with **Target agent:** and **Files:** metadata) into N shards (max 10), creates per-worktree Postgres DBs (gsd_wt1, gsd_wt2, …), links .review-squad/ via symlink so PM Cory context is shared, dispatches squad implement agents in parallel scoped to one phase each, then sequentially rebase-merges onto main with typecheck + lint validation between merges. Trivial import/formatting conflicts auto-resolve via prettier; non-trivial conflicts halt the chain. Auto-invokes /review on the merged range (Step 6.5). Standard ports — only ONE worktree runs dev services at a time; fleet enables parallel AGENT work (edits, unit tests), not parallel SERVICE operation.
-
/ui-iterate — test-driven theme iteration
Converts subjective theme tuning into a measurable loop. stevey-boy-choi-implement proposes N palette variants per round. Each gets applied to the theme file, the fitness suite runs (Playwright visual snapshot + axe-core accessibility + WCAG contrast check + palette-proximity to a target hex set), composite score is computed (weighted sum: contrast 0.35, palette 0.25, visual diff 0.15, axe 0.25), top 3 feed round R+1 as seeds. After K rounds, produces a ranked markdown report to .review-squad/<project>/ui-iterations/. Bootstraps Playwright toHaveScreenshot and installs @axe-core/playwright on first run. Always reverts the theme file to baseline — user applies a winner manually from the report’s palette diff.
-
/sync-upstream — squad meta-work sync
Automates the cp → git add → git commit → git push flow for squad meta-work. Detects changed files in ~/.claude/ across agents/, commands/ (incl. subdirs), project-rules/, templates/, hooks/. Auto-switches the active gh account to the repo owner for the push, switches back after. Never force-pushes. Stages files by name — never git add .. Supports --dry-run, --no-push, --message. Replaces the repeat pattern of manually copying + committing after each meta-edit.
-
/review Step 0 pre-flight gate
Before any reviewer agent spawns, the command verifies: session context (pwd, git branch --show-current, git status -sb, gh pr view), branch assertion against any linked PR (--pr N flag or auto-detected headRefName), and a validation gate that runs pnpm typecheck + pnpm lint if the project has those scripts. If typecheck or lint fails, the squad is NOT dispatched — user gets first 10 lines of the error output with a one-line override path (--skip-preflight). Reason: the review squad is expensive; it should not be invoked on code that doesn’t compile or lint clean.
-
/ship Step 1b.1 branch assertion
After the review gate but before any PR creation, compares git branch --show-current to gh pr view --json headRefName. On mismatch, exits immediately with the expected vs actual branch. Also detects stale review verdicts (HEAD has advanced beyond the reviewed commits); requires explicit --stale-ok override in that case. Closes the recurring friction where Claude reported on the wrong PR branch mid-session.
-
/ship Step 1g commit hygiene validation
Opt-in via @~/.claude/project-rules/commit-hygiene.md in the project’s CLAUDE.md. Hard gate on commit body lines exceeding 72 characters (pre-commit hooks on many repos reject these). Soft gate on prettier pass across changed files — offers auto-fix via follow-up commit. Advisory scan for stale imports after export removals (grep for consumers). Cross-references the Step 1f secret scan. Override with --skip-hygiene when justified. Fail-open behavior: if git log or git diff errors out, logs and continues — hygiene validation itself never blocks ship.
-
review-squad-gate.js — three new skip paths
The PostToolUse advisory now suppresses in three high-noise cases: (1) cwd is the Review_Squad repo itself (detected via git remote get-url origin matching /Review_Squad(\.git)?$) — the squad reviewing its own changes produces no useful verdict; (2) every edited file is under ~/.claude/ — personal harness config, not project code; (3) every edited file is pure docs (README, CHANGELOG, /docs/, *.txt) — markdown files in code paths (/commands/, /agents/, /skills/, /hooks/, /templates/, /project-rules/, /src/, /scripts/) still count as code. All three skips fail-open.
-
New
project-rules/ directory — opt-in per-project rules
Rules that apply to some projects, not globally. Reference via @~/.claude/project-rules/<name>.md from a project’s CLAUDE.md. Two rules ship: commit-hygiene.md (72-char body, prettier before stage, stale-imports cleanup, never-commit list, one-logical-change-per-commit, conventional-commit format) and dev-environment.md (worktree verification, lsof port checks, correct backgrounding, required-env checklist, workspace-scoped pnpm commands). The keep-global-small principle: CLAUDE.md holds always-true rules; project-rules/ holds opt-in-when-relevant rules.
-
/update-reviewsquad now syncs project-rules/*.md
The sync mechanism was extended to include project-rules/*.md in both first-run (contents API) and incremental (compare API) modes. Destination directory ~/.claude/project-rules/ is created if missing. Without this, /ship’s Step 1g reference to commit-hygiene.md would be a broken pointer for anyone who installed the squad fresh.
-
Gotchas sections added to five commands
Per Anthropic’s internal data showing skills-with-Gotchas measurably improve LLM accuracy, every V4.2 command has a
## Gotchas section with 4–6 specific pitfalls: /handoff (rolling overwrite, cwd-sensitive), /review-auto (Jared-flagged never auto-apply, separate commit per iteration, iteration 2+ re-prompt rules), /fleet (one worktree runs services at a time, Postgres admin required, Files metadata accuracy matters), /ui-iterate (reverts at end, HMR required, composite weights hardcoded), /sync-upstream (local-to-upstream only, account switching, never force-pushes).
-
Emily — UI Iteration History section
Emily’s review output template now includes a UI Iteration History section. When reviewing changes that apply a
/ui-iterate-selected variant, Emily checks .review-squad/<project>/ui-iterations/ for recent fitness reports and grounds her UX verdict in the measured composite score plus the rubric dimensions that drove selection. Rather than assessing aesthetics alone.
-
Stevey — UI Iteration Grounding check
In Frontend Review, when the changeset touches theme tokens or palette files, Stevey verifies the change matches a recent
/ui-iterate winning variant. Missing iteration report is a soft signal (not a block); applying a different variant than the report recommended gets called out. Theme work backed by measured fitness scores much higher than theme work by vibe.
-
README lifecycle table expanded
Five new command entries added with their squad agent involvement. Repository structure updated to show
project-rules/ directory and the V4.2-tagged commands. Version header block follows the existing changelog pattern.
-
Wiki pages added and updated
New Lifecycle Extensions page covers all five V4.2 commands with flow diagrams, usage examples, constraints, and gotchas. New Project Rules page explains the opt-in pattern and the two shipped rules. Home quick-start table and navigation updated. _Sidebar adds both new pages under Commands and Guides. Review Hook page documents the three new skip conditions.