Loading
chore(skills): add review-branch project skill
Why
Make /review-branch (the deep multi-lens 13-phase branch review) checked-in team tooling. The personal skill at ~/.claude/skills/review-branch/ lives only on individual machines, requires a third-party fullstack-dev-skills plugin install, and routes by remote URL. None of those are reasonable expectations for shared team tooling. After this MR, anyone who clones the repo gets the deep review out of the box, with no extra setup.
What (non-obvious)
- Methodology hand-off lines dropped (12 total). "Apply the X skill methodology" lines deleted from every phase intro. The inline checklists already encode the same checks. Teammates do not need
fullstack-dev-skillsinstalled. - Phase 13 expanded from 4 to 8 guardrails:
5. Format conformanceauto-detectsinternal/handlers/oci/conformance/at runtime. Severity flips from OBSERVATION to WARNING once the harness lands. No future edit required.6. Security mirror ruleBLOCKING heuristic. Regex requires co-occurrence of strict tokens (cve-\d|disclos|private|confidential). Barevulnorsecuritydoes not trigger (soupdate-vulnerability-scanner-depsandfix-csrf-middlewaredo not false-positive).SECURITY_MIRROR_OVERRIDE=1env var documented as an explicit downgrade.7. Label taxonomyOBSERVATION reminder citingdocs/dev/labels.md. Optionalglablookup escalates to WARNING when an MR exists withouttype::*.8. Plan-MR sequencingWARNING-only (not BLOCKING). Reviewers and authors decide case-by-case whether a branch warrants a plan. Avoids false-blocking small features misclassified by commit-prefix heuristics.
- AR conventions inlined. Path categories, build tags, query-plan policy, lint version, Conventional Commits scope rules. The
references/<project>.mdloader from the personal skill is deleted (one project, nothing to switch on). - Maintenance section near the top of
SKILL.mdlists whichfullstack-dev-skillsmethodologies were mirrored inline so future editors can diff against upstream changes when the plugin updates. Also carries a file-size tripwire: split intoreferences/phase-13.mdif any sub-checklist exceeds 12 lines or Phase 13 grows past 10 sub-items.
Test plan
- Vale runs clean: 0 errors, 0 warnings, 0 suggestions.
markdownlint-cli2excludes.claude/skills/**from project config (verified vianpx markdownlint-cli2 .claude/skills/review-branch/SKILL.mdreporting "Linting: 0 file(s)"). - No "Apply the X skill methodology" lines remain:
grep -cE '^Apply the .* skill methodolog(y|ies)\.$' .claude/skills/review-branch/SKILL.mdreturns 0. - Plugin methodology names confined to the
## Maintenancesection:awk '/^## /{section=$0} /\b(golang-pro|code-reviewer|security-reviewer|postgres-pro|database-optimizer|sre-engineer|monitoring-expert|go-perf|code-documenter|the-fool)\b/ && section !~ /Maintenance/' .claude/skills/review-branch/SKILL.mdreturns no lines. - Phase 13 has 8 numbered sub-items.
- All
../../../docs/...paths resolve (literal<placeholder>paths and the F5 auto-detect targetinternal/handlers/oci/conformance/are intentionally exempt). - Smoke test: run
/review-branchon a recent branch and verify it produces a structured report. Confirm sub-item 6 does not BLOCK on a benign branch name likeupdate-vulnerability-scanner-deps.
Notes
- Tooling-only change. Plan-file exemption per CLAUDE.md guardrail 1, which targets product features and initiatives.
- Out-of-scope follow-ups, tracked separately:
- Manual cleanup on the author's
~/.claude/: removereferences/artifact-registry.mdand trim Setup step 2 in the personalSKILL.md. Personal skill stays generic for non-AR repos (e.g. container-registry). - Workflow integration (mention
/review-branchinCLAUDE.md"Before You Start" ordocs/dev/README.md) deferred until the team has run the skill in anger.
- Manual cleanup on the author's