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/release-preflight.sh
View on GitHub#!/bin/bash
# release-preflight.sh
# Vendor-neutral pre-release verification for Harness release flow.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# project-root: use git repo root for generic project-root resolution
if [ -n "${HARNESS_RELEASE_PLUGIN_ROOT:-}" ]; then
PLUGIN_ROOT="$HARNESS_RELEASE_PLUGIN_ROOT"
else
PLUGIN_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
if [ -z "$PLUGIN_ROOT" ]; then
PLUGIN_ROOT="$(pwd)"
fi
fi
if [ "${1:-}" = "--help" ]; then
cat <<'EOF'
Usage: scripts/release-preflight.sh [--root PLUGIN_ROOT] [--dry-run]
--root PLUGIN_ROOT Override the plugin root directory (default: three levels up from this script)
Checks:
- git worktree cleanliness
- CHANGELOG.md / [Unreleased]
- env parity / healthcheck
- runtime residual scan
- sprint-contract schema
- CI status when available
EOF
exit 0
fi
while [ "$#" -gt 0 ]; do
case "$1" in
--root)
if [ "${2:-}" = "" ]; then
echo "error: --root requires a path" >&2
exit 2
fi
PLUGIN_ROOT="$2" # plugin-local: override plugin root
shift 2
;;
--dry-run)
shift
;;
*)
echo "error: unknown argument: $1" >&2
exit 2
;;
esac
done
if [ ! -d "$PLUGIN_ROOT" ]; then
echo "error: plugin root not found: $PLUGIN_ROOT" >&2
exit 1
fi
cd "$PLUGIN_ROOT" # plugin-local: operate from plugin root
GIT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PLUGIN_ROOT")" # project-root: user's git repository root
# Wrapper guard: if this project has a release-this skill, require it to be the entry point.
# release-this creates .claude/state/harness-release-wrapper.lock before delegating here.
_WRAPPER_SKILL="$GIT_ROOT/.claude/skills/release-this/SKILL.md"
_WRAPPER_LOCK="$GIT_ROOT/.claude/state/harness-release-wrapper.lock"
if [ -f "$_WRAPPER_SKILL" ] && [ ! -f "$_WRAPPER_LOCK" ]; then
echo "[FAIL] release-this wrapper detected — run /release-this instead of /harness-release directly." >&2
echo " To bypass: touch $GIT_ROOT/.claude/state/harness-release-wrapper.lock" >&2
exit 1
fi
PASS_COUNT=0
WARN_COUNT=0
FAIL_COUNT=0
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'
pass() {
echo -e "[PASS] $1"
PASS_COUNT=$((PASS_COUNT + 1))
}
warn() {
echo -e "[WARN] $1"
WARN_COUNT=$((WARN_COUNT + 1))
}
fail() {
echo -e "[FAIL] $1"
FAIL_COUNT=$((FAIL_COUNT + 1))
}
run_optional_command() {
local label="$1"
local command_text="$2"
local output_file
output_file="$(mktemp /tmp/harness-tmp.XXXXXX)"
if bash -lc "$command_text" >"$output_file" 2>&1; then
pass "$label"
else
fail "$label"
sed 's/^/ /' "$output_file"
fi
rm -f "$output_file"
}
extract_env_keys() {
local file="$1"
awk -F= '
/^[[:space:]]*#/ { next }
/^[[:space:]]*$/ { next }
{
line=$0
sub(/^[[:space:]]*export[[:space:]]+/, "", line)
split(line, parts, "=")
key=parts[1]
gsub(/[[:space:]]+$/, "", key)
if (key ~ /^[A-Za-z_][A-Za-z0-9_]*$/) {
print key
}
}
' "$file" | sort -u
}
check_git_clean() {
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
fail "git worktree"
return
fi
local status
status="$(git status --porcelain --untracked-files=normal)"
if [ -n "$status" ]; then
fail "working tree clean"
printf '%s\n' "$status" | sed 's/^/ /'
else
pass "working tree clean"
fi
}
check_changelog() {
local changelog="$GIT_ROOT/CHANGELOG.md" # project-root: CHANGELOG lives at git repo root
if [ ! -f "$changelog" ]; then
fail "CHANGELOG.md not found"
return
fi
if grep -q '^\## \[Unreleased\]' "$changelog"; then
pass "CHANGELOG.md has [Unreleased]"
else
fail "CHANGELOG.md has [Unreleased]"
fi
}
check_env_and_healthcheck() {
local env_ok=1
if [ -f .env.example ]; then
if [ ! -f .env ]; then
warn ".env missing for .env.example"
env_ok=0
else
local missing
missing="$(
comm -23 \
<(extract_env_keys .env.example) \
<(extract_env_keys .env)
)"
if [ -n "$missing" ]; then
fail ".env matches .env.example"
printf '%s\n' "$missing" | sed 's/^/ missing: /'
env_ok=0
else
pass ".env matches .env.example"
fi
fi
else
warn ".env.example not found; env parity skipped"
fi
if [ -n "${HARNESS_RELEASE_HEALTHCHECK_CMD:-}" ]; then
run_optional_command "healthcheck command" "$HARNESS_RELEASE_HEALTHCHECK_CMD"
return
fi
if [ -f package.json ]; then
local has_healthcheck=0
local has_preflight=0
if node -e 'const fs=require("fs"); const pkg=JSON.parse(fs.readFileSync("package.json","utf8")); process.exit(pkg.scripts && pkg.scripts.healthcheck ? 0 : 1)' >/dev/null 2>&1; then
has_healthcheck=1
fi
if node -e 'const fs=require("fs"); const pkg=JSON.parse(fs.readFileSync("package.json","utf8")); process.exit(pkg.scripts && pkg.scripts.preflight ? 0 : 1)' >/dev/null 2>&1; then
has_preflight=1
fi
if [ "$has_healthcheck" -eq 1 ]; then
run_optional_command "healthcheck command" "npm run healthcheck --silent"
return
fi
if [ "$has_preflight" -eq 1 ]; then
run_optional_command "healthcheck command" "npm run preflight --silent"
return
fi
fi
if [ "$env_ok" -eq 1 ]; then
warn "healthcheck command not configured"
elif [ ! -f .env ] && [ -f .env.example ]; then
warn "healthcheck command not configured"
fi
}
check_runtime_residuals() {
local residual_patterns="${HARNESS_RELEASE_RESIDUAL_PATTERNS:-mockData|dummy|fakeData|localhost|TODO|FIXME|test\\.skip|describe\\.skip|it\\.skip}"
local files=()
local file
# Use HARNESS_RELEASE_RESIDUAL_DIRS env var if set, otherwise scan all git-tracked files
if [ -n "${HARNESS_RELEASE_RESIDUAL_DIRS:-}" ]; then
SCAN_DIRS="$HARNESS_RELEASE_RESIDUAL_DIRS"
else
# Generic default: scan all git-tracked files (no directory filter)
SCAN_DIRS="."
fi
while IFS= read -r -d '' file; do
# Skip this script itself to avoid self-matching on residual pattern examples
if [ "$file" = ".claude/skills/release-this/scripts/release-preflight.sh" ]; then
continue
fi
# Apply directory filter if SCAN_DIRS is not "."
if [ "$SCAN_DIRS" != "." ]; then
local matched=0
for dir in $SCAN_DIRS; do
case "$file" in
"$dir"/*|"$dir")
matched=1
break
;;
esac
done
if [ "$matched" -eq 0 ]; then
continue
fi
fi
files+=("$file")
done < <(git ls-files -z)
if [ "${#files[@]}" -eq 0 ]; then
warn "runtime residual scan skipped"
return
fi
local matches
if command -v rg >/dev/null 2>&1; then
matches="$(rg -n -I --no-heading -e "$residual_patterns" -- "${files[@]}" 2>/dev/null || true)"
else
matches="$(grep -nIH -E "$residual_patterns" -- "${files[@]}" 2>/dev/null || true)"
fi
if [ -n "$matches" ]; then
warn "runtime residual scan"
printf '%s\n' "$matches" | head -20 | sed 's/^/ /'
else
pass "runtime residual scan"
fi
}
check_sprint_contract_schema() {
local contracts_dir="${GIT_ROOT}/.claude/state/contracts" # project-root: sprint contracts
# Skip gracefully when no sprint contracts directory exists (not a harness project)
if [ ! -d "$contracts_dir" ]; then
pass "sprint-contract schema (skipped — no contracts directory)"
return 0
fi
local contract_dir="$contracts_dir"
local contract_files=()
local file
while IFS= read -r file; do
contract_files+=("$file")
done < <(find "$contract_dir" -type f -name '*.sprint-contract.json' | sort)
if [ "${#contract_files[@]}" -eq 0 ]; then
warn "sprint-contract schema scan skipped"
return
fi
local output_file
output_file="$(mktemp /tmp/harness-tmp.XXXXXX)"
if node - "${contract_files[@]}" >"$output_file" 2>&1 <<'NODE'
const fs = require('fs');
const files = process.argv.slice(2);
const allowedProfiles = new Set(['static', 'runtime', 'browser', 'security', 'ui-rubric']);
const allowedLoopPacing = new Set(['worker', 'ci', 'plateau', 'night']);
const allowedBrowserVerdicts = new Set([
'APPROVE',
'REQUEST_CHANGES',
'PENDING_BROWSER',
'SKIPPED',
'DOWNGRADE_TO_STATIC',
]);
let hasErrors = false;
function report(file, issues) {
if (issues.length === 0) {
return;
}
hasErrors = true;
console.log(file);
for (const issue of issues) {
console.log(` - ${issue}`);
}
}
for (const file of files) {
let contract;
try {
contract = JSON.parse(fs.readFileSync(file, 'utf8'));
} catch (error) {
report(file, [`invalid JSON: ${error.message}`]);
continue;
}
const review = contract.review || {};
const issues = [];
if (!allowedProfiles.has(review.reviewer_profile)) {
issues.push(
`review.reviewer_profile must be one of ${Array.from(allowedProfiles).join('|')}; got ${JSON.stringify(review.reviewer_profile)}`
);
}
if (review.max_iterations !== undefined) {
if (!Number.isInteger(review.max_iterations) || review.max_iterations < 1 || review.max_iterations > 30) {
issues.push(`review.max_iterations must be an integer between 1 and 30; got ${JSON.stringify(review.max_iterations)}`);
}
}
if (review.rubric_target !== undefined) {
const target = review.rubric_target;
if (target === null || Array.isArray(target) || typeof target !== 'object') {
issues.push('review.rubric_target must be an object');
} else {
for (const [key, value] of Object.entries(target)) {
if (typeof value !== 'number' || Number.isNaN(value)) {
issues.push(`review.rubric_target.${key} must be numeric; got ${JSON.stringify(value)}`);
}
}
}
}
if (review.loop_pacing !== undefined) {
if (typeof review.loop_pacing !== 'string' || !allowedLoopPacing.has(review.loop_pacing)) {
issues.push(`review.loop_pacing must be one of ${Array.from(allowedLoopPacing).join('|')}; got ${JSON.stringify(review.loop_pacing)}`);
}
}
if (review.browser_verdict !== undefined) {
if (typeof review.browser_verdict !== 'string' || !allowedBrowserVerdicts.has(review.browser_verdict)) {
issues.push(
`review.browser_verdict must be one of ${Array.from(allowedBrowserVerdicts).join('|')}; got ${JSON.stringify(review.browser_verdict)}`
);
}
}
report(file, issues);
}
process.exit(hasErrors ? 1 : 0);
NODE
then
pass "sprint-contract schema (${#contract_files[@]} files)"
else
fail "sprint-contract schema"
sed 's/^/ /' "$output_file"
fi
rm -f "$output_file"
}
check_ci_status() {
if [ -n "${HARNESS_RELEASE_CI_STATUS_CMD:-}" ]; then
run_optional_command "CI status" "$HARNESS_RELEASE_CI_STATUS_CMD"
return
fi
if ! command -v gh >/dev/null 2>&1; then
warn "CI status unavailable (gh not installed)"
return
fi
local branch
branch="$(git branch --show-current 2>/dev/null || true)"
if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
warn "CI status unavailable (detached HEAD)"
return
fi
local gh_output
gh_output="$(gh run list --branch "$branch" --limit 1 --json status,conclusion 2>/dev/null || true)"
if [ -z "$gh_output" ]; then
warn "CI status unavailable (no GitHub Actions data)"
return
fi
local status
local conclusion
if command -v jq >/dev/null 2>&1; then
status="$(printf '%s' "$gh_output" | jq -r '.[0].status // empty')"
conclusion="$(printf '%s' "$gh_output" | jq -r '.[0].conclusion // empty')"
else
status="$(printf '%s' "$gh_output" | sed -n 's/.*"status":"\([^"]*\)".*/\1/p' | head -n 1)"
conclusion="$(printf '%s' "$gh_output" | sed -n 's/.*"conclusion":"\([^"]*\)".*/\1/p' | head -n 1)"
fi
if [ "$status" = "completed" ] && [ "$conclusion" = "success" ]; then
pass "CI status"
else
fail "CI status"
printf ' latest run status=%s conclusion=%s\n' "${status:-unknown}" "${conclusion:-unknown}"
fi
}
printf 'Release preflight: %s\n' "$PLUGIN_ROOT"
echo "----------------------------------------"
check_git_clean
check_changelog
check_env_and_healthcheck
check_runtime_residuals
check_sprint_contract_schema
check_ci_status
echo "----------------------------------------"
printf 'Summary: %d passed, %d warnings, %d failed\n' "$PASS_COUNT" "$WARN_COUNT" "$FAIL_COUNT"
if [ "$FAIL_COUNT" -gt 0 ]; then
exit 1
fi
exit 0
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: 472k | 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 |