Skip to content

tim-hub/powerball-harness / .claude/skills/release-this

release-this

Verified

Orchestrates the full powerball-harness plugin release with build, validation, version bump, CHANGELOG, tag, and GitHub Release. Use when releasing this plugin.

FileKindSize
SKILL.mdskill md6.9 KB
references/versioning-rules.mdmarkdown2.5 KB
references/writing-changelog.mdmarkdown2.9 KB
scripts/bench-residue.shexecutablescript1.2 KB
scripts/check-consistency.shexecutablescript19.7 KB
scripts/check-residue.pyscript16.2 KB
scripts/release-preflight.shexecutablescript12.2 KB
scripts/sync-version.shexecutablescript6.6 KB
scripts/validate-release-notes.shexecutablescript2.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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall