tim-hub/powerball-harness / .claude/skills/release-this
release-this
VerifiedOrchestrates the full powerball-harness plugin release with build, validation, version bump, CHANGELOG, tag, and GitHub Release. Use when releasing this plugin.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.9 KB |
| references/versioning-rules.md | markdown | 2.5 KB |
| references/writing-changelog.md | markdown | 2.9 KB |
| scripts/bench-residue.shexecutable | script | 1.2 KB |
| scripts/check-consistency.shexecutable | script | 19.7 KB |
| scripts/check-residue.py | script | 16.2 KB |
| scripts/release-preflight.shexecutable | script | 12.2 KB |
| scripts/sync-version.shexecutable | script | 6.6 KB |
| scripts/validate-release-notes.shexecutable | script | 2.4 KB |
scripts/check-residue.py
View on GitHub#!/usr/bin/env python3
# check-residue.py — Migration Residue Scanner (Phase 40)
#
# Purpose:
# Load .claude/rules/deleted-concepts.yaml and detect whether deleted paths or
# concepts still exist anywhere in the repository.
# Exits 0 if none found, exits 1 if one or more are found.
#
# Usage:
# python3 .claude/skills/release-this/scripts/check-residue.py
import subprocess
import sys
import os
import time
import re
import pathlib
# ─── Resolve repository root ──────────────────────────────────────────────────
# Script lives at: .claude/skills/release-this/scripts/check-residue.py
# Repo root is 4 levels up.
REPO_ROOT = str((pathlib.Path(__file__).parent / "../../../../").resolve())
try:
import yaml
def _load_yaml(path):
with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f)
except ImportError:
# PyYAML not installed — fall back to an indent-aware minimal parser.
# Handles the known schema: version, deleted_paths[], deleted_concepts[]
# each with path/term, deleted_in, reason, allowlist[], optional fields.
def _load_yaml(path):
"""Indent-aware YAML loader for deleted-concepts.yaml (stdlib only)."""
with open(path, "r", encoding="utf-8") as f:
lines = f.readlines()
result = {"version": 1, "deleted_paths": [], "deleted_concepts": []}
current_section = None # 'deleted_paths' or 'deleted_concepts'
current_entry = None # dict being built
in_allowlist = False # True when inside an allowlist: block
allowlist_indent = -1 # indent level of allowlist items
def _strip_value(s):
"""Strip inline comments, then quotes from a YAML scalar value."""
s = s.strip()
if s.startswith('"'):
end = s.find('"', 1)
return s[1:end] if end != -1 else s[1:]
if s.startswith("'"):
end = s.find("'", 1)
return s[1:end] if end != -1 else s[1:]
if ' #' in s:
s = s[:s.index(' #')]
elif s.startswith('#'):
return ''
return s.strip()
def flush_entry():
if current_entry is not None and current_section is not None:
result[current_section].append(current_entry)
for raw in lines:
if not raw.strip() or raw.strip().startswith('#'):
continue
indent = len(raw) - len(raw.lstrip())
stripped = raw.strip()
if indent == 0:
if stripped.startswith('version:'):
m = re.match(r'version:\s*(\d+)', stripped)
if m:
result['version'] = int(m.group(1))
elif stripped.startswith('deleted_paths:'):
flush_entry()
current_section = 'deleted_paths'
current_entry = None
in_allowlist = False
elif stripped.startswith('deleted_concepts:'):
flush_entry()
current_section = 'deleted_concepts'
current_entry = None
in_allowlist = False
continue
if current_section is None:
continue
if stripped.startswith('- ') and indent <= 4:
flush_entry()
current_entry = {'allowlist': []}
in_allowlist = False
rest = stripped[2:]
if ':' in rest:
k, v = rest.split(':', 1)
val = _strip_value(v)
current_entry[k.strip()] = val if val else None
continue
if current_entry is None:
continue
if in_allowlist and indent > allowlist_indent - 4:
if stripped.startswith('- '):
item = _strip_value(stripped[2:])
if item:
current_entry['allowlist'].append(item)
continue
else:
in_allowlist = False
if stripped.startswith('allowlist:'):
in_allowlist = True
allowlist_indent = indent + 2
continue
if ':' in stripped and not stripped.startswith('-'):
k, v = stripped.split(':', 1)
k = k.strip()
v = _strip_value(v)
if k == '_scan_disabled':
current_entry[k] = v.lower() in ('true', '1', 'yes')
elif v:
current_entry[k] = v
else:
current_entry[k] = None
flush_entry()
return result
YAML_PATH = os.path.join(REPO_ROOT, ".claude/rules/deleted-concepts.yaml")
start_time = time.time()
# ─── Load YAML ─────────────────────────────────────────────────────────────
if not os.path.exists(YAML_PATH):
print(f"ERROR: {YAML_PATH} not found", file=sys.stderr)
sys.exit(2)
config = _load_yaml(YAML_PATH)
deleted_paths = config.get("deleted_paths", [])
deleted_concepts = config.get("deleted_concepts", [])
# Skip entries that have the scan_disabled flag set
deleted_concepts = [c for c in deleted_concepts if not c.get("_scan_disabled", False)]
n_paths = len(deleted_paths)
n_concepts = len(deleted_concepts)
print("=== Migration Residue Scan ===")
print(f"Loaded: .claude/rules/deleted-concepts.yaml")
print(f"Entries: {n_paths} deleted_paths + {n_concepts} deleted_concepts")
print()
# ─── Allowlist check ─────────────────────────────────────────────────────────
def is_allowlisted(filepath: str, allowlist: list) -> bool:
rel = filepath.lstrip("./")
for entry in allowlist:
entry_clean = entry.lstrip("./")
if rel.startswith(entry_clean):
return True
return False
# ─── Scan backends ────────────────────────────────────────────────────────────
def _rg_available() -> bool:
try:
subprocess.run(["rg", "--version"], capture_output=True, check=True)
return True
except (FileNotFoundError, subprocess.CalledProcessError):
return False
def _batch_scan_rg(terms: list, repo_root: str) -> dict:
"""One rg pass for all terms. Returns {term: [(filepath, linenum, content)]}."""
args = [
"rg", "-F", "-n", "--no-heading", "--with-filename",
# --no-ignore: scan ALL files regardless of .gitignore / global excludes.
# Without it, rg silently skips tracked files matched by a broad global
# gitignore (core.excludesfile), making the residue scan a false-clean no-op.
# --hidden: also scan dotfiles/dot-dirs (.claude/, .githooks/, .github/).
# Without it, rg skips the entire .claude/ tree — where skills/rules/agents
# live — so re-introduced references there would go undetected.
"--no-ignore",
"--hidden",
"--glob", "!.git",
"--glob", "!node_modules",
"--glob", "!.claude/worktrees",
]
for term in terms:
args.extend(["-e", term])
args.append(".")
result = subprocess.run(args, cwd=repo_root, capture_output=True, text=True)
# rg exits 0 on match, 1 on no match, 2 on error
if result.returncode == 2:
raise RuntimeError(f"rg error: {result.stderr.strip()}")
hits = {term: [] for term in terms}
for line in result.stdout.splitlines():
m = re.match(r"^(.+?):(\d+):(.*)$", line)
if not m:
continue
filepath, linenum, content = m.group(1), int(m.group(2)), m.group(3).strip()
for term in terms:
if term in content:
hits[term].append((filepath, linenum, content))
return hits
def _batch_scan_grep(terms: list, repo_root: str) -> dict:
"""Fallback: sequential grep per term (legacy behaviour)."""
hits = {term: [] for term in terms}
for term in terms:
try:
r = subprocess.run(
["grep", "-rln", "-F", "--exclude-dir=.git", term, "."],
cwd=repo_root, capture_output=True, text=True,
)
for filepath in (f.strip() for f in r.stdout.splitlines() if f.strip()):
r2 = subprocess.run(
["grep", "-n", "-F", term, filepath],
cwd=repo_root, capture_output=True, text=True,
)
for ln_line in r2.stdout.splitlines():
lm = re.match(r"^(\d+):(.*)$", ln_line)
if lm:
hits[term].append((filepath, int(lm.group(1)), lm.group(2).strip()))
except Exception as e:
print(f" WARNING: grep error for '{term}': {e}", file=sys.stderr)
return hits
def batch_scan(terms: list, repo_root: str, backend: str = "auto") -> dict:
"""
Scan all terms in one pass. Returns {term: [(filepath, linenum, content)]}.
Set RESIDUE_SCANNER_BACKEND=rg|grep|auto to override; default is auto (rg if available).
"""
if not terms:
return {}
use_rg = backend == "rg" or (backend == "auto" and _rg_available())
if use_rg:
try:
return _batch_scan_rg(terms, repo_root)
except (FileNotFoundError, RuntimeError) as e:
print(f" WARNING: rg failed ({e}), falling back to grep", file=sys.stderr)
return _batch_scan_grep(terms, repo_root)
def grep_h1_v3_files(repo_root: str) -> list:
"""Regex scan for H1 titles with (v3) suffix — kept separate as it uses a regex pattern."""
try:
result = subprocess.run(
["grep", "-rln", "--include=*.md", "--exclude-dir=.git", r"^# .*(v3)", "."],
cwd=repo_root, capture_output=True, text=True,
)
if result.returncode not in (0, 1):
return []
return [f.strip() for f in result.stdout.splitlines() if f.strip()]
except Exception:
return []
# ─── Run scan ─────────────────────────────────────────────────────────────────
violations = 0
violation_files = set()
SCAN_BACKEND = os.environ.get("RESIDUE_SCANNER_BACKEND", "auto")
_PATH_DEFAULT_ALLOWLIST = [
"CHANGELOG.md",
".claude/memory/archive/",
".claude/worktrees/",
".claude/state/",
"out/",
"output/",
"benchmarks/",
"tests/validate-plugin-v3.sh",
".claude/rules/deleted-concepts.yaml",
".claude/skills/release-this/scripts/check-residue.py",
"go/.claude/", # Go-module-local state/fixtures (changed-files.jsonl etc.) — ephemeral, like .claude/state/
"go/cmd/harness/plan-cli/.claude/",
"docs/spikes/plugin-name-cleanup-inventory.md", # historical spike inventory: intentionally lists old paths/skills
]
_CONCEPT_DEFAULT_ALLOWLIST = [
"CHANGELOG.md",
".claude/memory/archive/",
".claude/worktrees/",
".claude/state/",
"out/",
"output/",
"benchmarks/",
".claude/rules/deleted-concepts.yaml",
".claude/skills/release-this/scripts/check-residue.py",
"go/.claude/", # Go-module-local state/fixtures (changed-files.jsonl etc.) — ephemeral, like .claude/state/
"go/cmd/harness/plan-cli/.claude/",
"docs/spikes/plugin-name-cleanup-inventory.md", # historical spike inventory: intentionally lists old paths/skills
"tests/validate-plugin-v3.sh",
]
# ── Collect all scan terms for a single batched pass ──
all_terms = []
for entry in deleted_paths:
all_terms.append(entry["path"])
for entry in deleted_concepts:
if not entry.get("_scan_disabled", False):
all_terms.append(entry["term"])
if entry.get("term_ja"):
all_terms.append(entry["term_ja"])
print(f"[scanning {len(all_terms)} terms in one pass (backend={SCAN_BACKEND})...]")
all_hits = batch_scan(all_terms, REPO_ROOT, backend=SCAN_BACKEND)
def _report_hits(term: str, effective_allowlist: list) -> list:
"""Filter hits for term through allowlist; return list of (filepath, linenum, content)."""
return [
(f, ln, c)
for f, ln, c in all_hits.get(term, [])
if not is_allowlisted(f, effective_allowlist)
]
def _show_violations(term: str, filtered: list, label: str, suffix: str = "") -> None:
"""Print violation block and update global counters."""
global violations
by_file = {}
for f, ln, c in filtered:
by_file.setdefault(f, []).append((ln, c))
violations += len(by_file)
violation_files.update(by_file.keys())
print(f" ✗ {label}")
for f, lines in by_file.items():
for lineno, content in lines[:3]:
print(f" {f}:L{lineno} — \"{content}\"")
if suffix:
print(f" {suffix}")
print()
# ── Check deleted_paths ──
print("[checking deleted_paths...]")
for entry in deleted_paths:
path_term = entry["path"]
effective_allowlist = list(set(entry.get("allowlist", []) + _PATH_DEFAULT_ALLOWLIST))
filtered = _report_hits(path_term, effective_allowlist)
if filtered:
reason = entry.get("reason", "")
reason_display = f"{reason[:60]}..." if len(reason) > 60 else reason
_show_violations(path_term, filtered,
label=path_term,
suffix=f"(matched entry: {path_term}, reason: \"{reason_display}\")")
# ── Check deleted_concepts ──
print("[checking deleted_concepts...]")
for entry in deleted_concepts:
if entry.get("_scan_disabled", False):
continue
term = entry["term"]
term_ja = entry.get("term_ja")
replacement = entry.get("replacement", "")
effective_allowlist = list(set(entry.get("allowlist", []) + _CONCEPT_DEFAULT_ALLOWLIST))
display_replacement = f" → {replacement}" if replacement else ""
for scan_term in ([term] + ([term_ja] if term_ja else [])):
filtered = _report_hits(scan_term, effective_allowlist)
if filtered:
_show_violations(scan_term, filtered,
label=f"\"{scan_term}\"",
suffix=f"(matched entry: {scan_term}{display_replacement})")
# ── Scan for H1 (v3) suffix (regex — separate pass) ──
print("[scanning H1 (v3) suffix in *.md files...]")
h1_allowlist = [
"CHANGELOG.md",
".claude/memory/archive/",
".claude/worktrees/",
".claude/state/",
"out/",
"output/",
"benchmarks/",
".claude/rules/",
".claude/skills/release-this/scripts/check-residue.py",
".claude/rules/deleted-concepts.yaml",
"tests/validate-plugin-v3.sh",
]
h1_files = grep_h1_v3_files(REPO_ROOT)
h1_filtered = [f for f in h1_files if not is_allowlisted(f, h1_allowlist)]
if h1_filtered:
violations += len(h1_filtered)
violation_files.update(h1_filtered)
print(f" ✗ H1 title with (v3) suffix")
for f in h1_filtered:
try:
result = subprocess.run(
["grep", "-n", r"^# .*(v3)", f],
cwd=REPO_ROOT, capture_output=True, text=True,
)
for line in result.stdout.splitlines()[:3]:
m = re.match(r"^(\d+):(.*)$", line)
if m:
print(f" {f}:L{m.group(1)} — \"{m.group(2).strip()}\"")
except Exception:
print(f" {f}")
print(" (matched entry: H1 (v3) suffix → remove version suffix from H1 titles)")
print()
# ─── Summary ──────────────────────────────────────────────────────────────────
elapsed = time.time() - start_time
print("=== Summary ===")
if violations == 0:
print(" ✓ No migration residue detected")
print(f" Scan duration: {elapsed:.1f}s")
print(" Exit: 0")
sys.exit(0)
else:
print(f" Violations: {violations} (in {len(violation_files)} files)")
print(f" Scan duration: {elapsed:.1f}s")
print(" Exit: 1 (residue detected)")
sys.exit(1)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |