Skip to content

jeremylongshore/tons-of-skills-marketplace / plugins/community/contributing-clanker/skills/contribute-prepare

contribute-prepare

Verified

Prepare an OSS contribution locally after a read-only contribution audit. Creates explicitly scoped candidate records, repository dossiers, worktrees, test evidence, and gate results, but never publishes to GitHub. Use when the user has selected an issue and asks to set up, research, implement, test, or draft the contribution. Trigger with "/contribute-prepare" or "prepare this contribution locally".

FileKindSize
SKILL.mdskill md5.1 KB
agents/draft-writer.mdmarkdown2.0 KB
agents/repo-analyzer.mdmarkdown3.1 KB
agents/researcher.mdmarkdown10.5 KB
agents/scout.mdmarkdown7.5 KB
agents/test-runner.mdmarkdown3.5 KB
assets/claim-template.mdmarkdown714 B
assets/evidence-template.mdmarkdown532 B
assets/pr-template.mdmarkdown890 B
references/candidate-file-format.mdmarkdown9.3 KB
references/workflow-guide.mdmarkdown3.9 KB
scripts/audit-overrides.shexecutablescript7.3 KB
scripts/catalog-coverage.shexecutablescript4.0 KB
scripts/check.shexecutablescript1.1 KB
scripts/gate-runner.shexecutablescript8.9 KB
scripts/gates/a01-already-assigned.shexecutablescript1.1 KB
scripts/gates/a02-already-shipped.shexecutablescript1.3 KB
scripts/gates/a03-duplicate-flagged.shexecutablescript851 B
scripts/gates/a04-issue-age.shexecutablescript3.8 KB
scripts/gates/a05-issue-still-open.shexecutablescript1.6 KB
scripts/gates/a06-claim-etiquette-required.shexecutablescript1.6 KB
scripts/gates/a09-mention-routing.shexecutablescript2.1 KB
scripts/gates/b01-base-branch.shexecutablescript969 B
scripts/gates/b02-branch-naming.shexecutablescript1.0 KB
scripts/gates/b03-clone-fresh.shexecutablescript1.0 KB
scripts/gates/b05-dco-signoff.shexecutablescript1.5 KB
scripts/gates/b06-commit-format.shexecutablescript1.4 KB
scripts/gates/b07-scope-files.shexecutablescript2.1 KB
scripts/gates/b12-new-deps.shexecutablescript1.7 KB
scripts/gates/b14-local-checks.shexecutablescript1.7 KB
scripts/gates/b16-local-check-allowlist.shexecutablescript1.8 KB
scripts/gates/c01-draft-first.shexecutablescript902 B
scripts/gates/c02-pr-title-format.shexecutablescript1.2 KB
scripts/gates/c03-pr-body-sections.shexecutablescript2.0 KB
scripts/gates/c04-ui-screenshots.shexecutablescript1.6 KB
scripts/gates/c05-test-evidence.shexecutablescript1.4 KB
scripts/gates/c07-coauthor-banned.shexecutablescript1.2 KB
scripts/gates/c09-issue-link.shexecutablescript1.5 KB
scripts/gates/c11-no-force-push.shexecutablescript1.3 KB
scripts/gates/c12-ci-green.shexecutablescript1.2 KB
scripts/gates/c13-bots-passed.shexecutablescript2.1 KB
scripts/gates/c16-no-self-merge.shexecutablescript914 B
scripts/gates/c19-body-claim-vs-diff.shexecutablescript2.9 KB
scripts/gates/d02-no-ai-bug-reports.shexecutablescript1.4 KB
scripts/gates/d03-no-ai-pr-reviews.shexecutablescript1.1 KB
scripts/gates/d05-no-reopen.shexecutablescript1.1 KB
scripts/gates/e02-ai-strike-track.shexecutablescript2.7 KB
scripts/gates/e04-fork-target.shexecutablescript1.5 KB
scripts/gates/f01-license-compat.shexecutablescript3.5 KB
scripts/gates/f03-fixtures-clean.shexecutablescript1.2 KB
scripts/gates/f04-override-disclosure.shexecutablescript2.4 KB
scripts/gates/g01-no-vendored-edits.shexecutablescript1.9 KB
scripts/gates/g02-protected-paths.shexecutablescript1.2 KB
scripts/gates/g03-no-changelog-edits.shexecutablescript1.4 KB
scripts/gates/g04-no-version-bump.shexecutablescript1.4 KB
scripts/gates/g06-override-rate-limit.shexecutablescript1.5 KB
scripts/gates/lib/preamble.shexecutablescript4.8 KB
scripts/lint-candidate.shexecutablescript5.1 KB
scripts/researcher-build.shexecutablescript17.6 KB
scripts/researcher-refresh.pyscript4.9 KB
scripts/setup.shexecutablescript1.7 KB
scripts/test-known-traps.shexecutablescript5.4 KB
scripts/test-override-audit.shexecutablescript3.5 KB
scripts/test-plug-in.shexecutablescript4.0 KB
scripts/test-scout-refresh.shexecutablescript4.9 KB
scripts/test-stale-dossier-refresh.shexecutablescript3.7 KB
scripts/transition.shexecutablescript10.3 KB

scripts/transition.sh

View on GitHub
#!/usr/bin/env bash
# transition.sh — invoked by /contribute SKILL.md on every lifecycle transition.
# This is the single chokepoint between "user wants to take action" and
# "external action happens." Wraps gate-runner + override resolution +
# atomic candidate update.
#
# Usage:
#   transition.sh <action> <candidate-path> [options]
#     action: "shortlist→claimed", "claimed→working", etc.
#   options:
#     --dossier <path>            Override dossier path (default: derive from candidate)
#     --override-gate <id> <reason>  Pre-record an override before running gates (repeatable)
#     --dry-run                   Run gates, print verdict, do NOT mutate candidate
#     --max-gate-age <seconds>    Reject if last gate run for this candidate is older
#                                  (TOCTOU mitigation; default 60)
#
# Exit code: 0 if transition allowed, 1 if BLOCKed (effective after overrides).

set -euo pipefail

: "${CONTRIBUTE_STATE_DIR:?CONTRIBUTE_STATE_DIR must be explicitly set}"
: "${CONTRIBUTE_WORKSPACE_DIR:?CONTRIBUTE_WORKSPACE_DIR must be explicitly set}"
export CONTRIBUTE_STATE_DIR CONTRIBUTE_WORKSPACE_DIR

ACTION="${1:-}"
CANDIDATE="${2:-}"
shift 2 2>/dev/null || true

if [[ -z "$ACTION" || -z "$CANDIDATE" ]]; then
  echo "usage: $0 <action> <candidate-path> [--dossier PATH] [--override-gate ID REASON ...] [--dry-run] [--max-gate-age SEC]" >&2
  exit 64
fi

if [[ ! -f "$CANDIDATE" ]]; then
  echo "candidate not found: $CANDIDATE" >&2
  exit 65
fi

DOSSIER=""
DRY_RUN=0
MAX_GATE_AGE=60
declare -a OVERRIDES_NEW=()  # pairs: gate id, reason

while [[ $# -gt 0 ]]; do
  case "$1" in
    --dossier)
      DOSSIER="$2"; shift 2 ;;
    --override-gate)
      OVERRIDES_NEW+=("$2" "$3"); shift 3 ;;
    --dry-run)
      DRY_RUN=1; shift ;;
    --max-gate-age)
      # shellcheck disable=SC2034 # reserved for TOCTOU mitigation
      MAX_GATE_AGE="$2"; shift 2 ;;
    *)
      echo "unknown option: $1" >&2; exit 64 ;;
  esac
done

LOG="$CONTRIBUTE_STATE_DIR/log.jsonl"
NOW=$(/usr/bin/date -u +%Y-%m-%dT%H:%M:%SZ)

# Derive dossier path from candidate's repo if not supplied
if [[ -z "$DOSSIER" ]]; then
  REPO=$(/usr/bin/awk '/^---$/{fm=!fm?1:2;next} fm==1 && /^repo:/{sub(/^repo:[[:space:]]*/,""); print; exit}' "$CANDIDATE")
  if [[ -n "$REPO" ]]; then
    SLUG=$(/usr/bin/echo "$REPO" | /usr/bin/tr '/' '_')_; SLUG="${SLUG%_}"  # placeholder; researcher uses double-underscore
    SLUG=$(/usr/bin/echo "$REPO" | /usr/bin/sed 's,/,__,')
    CAND_DOSSIER="$CONTRIBUTE_STATE_DIR/research/${SLUG}.md"
    [[ -f "$CAND_DOSSIER" ]] && DOSSIER="$CAND_DOSSIER"
  fi
fi

# Pre-record any overrides into the candidate file (atomic temp+rename).
#
# Earlier implementation used `awk -v RS='---'` to insert `overrides: []`
# before the closing frontmatter delimiter, then `sed -i "/^overrides:/a"`
# to append each entry. That path corrupted YAML: the awk RS=--- handling
# mangled the opening delimiter to "------" (6 dashes) and the sed
# append landed entries OUTSIDE the array as sibling list items rather
# than children of `overrides`.
#
# Replace with a Python yaml round-trip — parse frontmatter, append to
# the overrides list as proper YAML mapping entries, re-serialize. The
# body (everything after the second `---`) passes through unchanged.
if [[ "${#OVERRIDES_NEW[@]}" -gt 0 ]]; then
  if [[ "$DRY_RUN" -eq 1 ]]; then
    echo "(dry-run) would record ${#OVERRIDES_NEW[@]} overrides; skipping write" >&2
  else
    TMP="${CANDIDATE}.tmp.$$"
    # Build a flat list of "gate=reason" pairs for the Python helper.
    # Use NUL as field separator to handle reasons containing any char.
    PAIRS_FILE="${CANDIDATE}.pairs.$$"
    : > "$PAIRS_FILE"
    i=0
    while [[ $i -lt ${#OVERRIDES_NEW[@]} ]]; do
      /usr/bin/printf '%s\0%s\0' "${OVERRIDES_NEW[$i]}" "${OVERRIDES_NEW[$((i+1))]}" >> "$PAIRS_FILE"
      i=$((i+2))
    done

    /usr/bin/python3 - "$CANDIDATE" "$NOW" "$PAIRS_FILE" "$TMP" <<'PYEOF'
import sys, yaml

cand_path, now_iso, pairs_path, out_path = sys.argv[1:5]

with open(cand_path) as f:
    text = f.read()

# Split frontmatter from body (markdown convention: --- on its own line)
lines = text.split('\n')
if not lines or lines[0].strip() != '---':
    sys.stderr.write("transition: candidate has no opening frontmatter delimiter\n")
    sys.exit(2)
try:
    end = lines.index('---', 1)
except ValueError:
    sys.stderr.write("transition: candidate has no closing frontmatter delimiter\n")
    sys.exit(2)

fm_text = '\n'.join(lines[1:end])
body_text = '\n'.join(lines[end+1:])

fm = yaml.safe_load(fm_text) or {}
if not isinstance(fm, dict):
    sys.stderr.write("transition: frontmatter is not a mapping\n")
    sys.exit(2)

if 'overrides' not in fm or fm['overrides'] is None:
    fm['overrides'] = []
if not isinstance(fm['overrides'], list):
    sys.stderr.write("transition: existing overrides field is not a list\n")
    sys.exit(2)

# Read NUL-separated pairs from pairs_path: gate, reason, gate, reason, ...
with open(pairs_path, 'rb') as f:
    raw = f.read()
parts = raw.split(b'\x00')
# Trailing NUL produces an empty final element — drop it.
if parts and parts[-1] == b'':
    parts.pop()
if len(parts) % 2 != 0:
    sys.stderr.write("transition: malformed override pairs (odd count)\n")
    sys.exit(2)

for i in range(0, len(parts), 2):
    gate = parts[i].decode('utf-8')
    reason = parts[i+1].decode('utf-8')
    fm['overrides'].append({'gate': gate, 'reason': reason, 'at': now_iso})

# Re-serialize. default_flow_style=False keeps blocks readable.
new_fm = yaml.safe_dump(fm, default_flow_style=False, sort_keys=False, allow_unicode=True).rstrip('\n')
new_text = '---\n' + new_fm + '\n---\n' + body_text

with open(out_path, 'w') as f:
    f.write(new_text)
PYEOF

    PY_EXIT=$?
    /usr/bin/rm -f "$PAIRS_FILE"
    if [[ "$PY_EXIT" -ne 0 ]]; then
      /usr/bin/rm -f "$TMP"
      echo "transition: yaml round-trip failed (exit $PY_EXIT) — candidate not modified" >&2
      exit 65
    fi

    /usr/bin/mv "$TMP" "$CANDIDATE"  # atomic rename

    # Log each override
    i=0
    while [[ $i -lt ${#OVERRIDES_NEW[@]} ]]; do
      OG="${OVERRIDES_NEW[$i]}"
      OR="${OVERRIDES_NEW[$((i+1))]}"
      i=$((i+2))
      jq --null-input --compact-output --arg ts "$NOW" --arg gate "$OG" --arg reason "$OR" --arg cand "$CANDIDATE" \
        '{ts: $ts, event: "gate_override", details: {gate: $gate, reason: $reason, candidate: $cand}}' >> "$LOG"
    done
  fi
fi

# Advisory: warn on missing required body sections per target status.
# Per skills/contribute/references/candidate-file-format.md § "Required
# sections by lifecycle stage". WARN (not BLOCK) — backfilled candidates
# legitimately came in mid-lifecycle without early-stage sections.
TARGET_STATUS="${ACTION##*→}"
REQUIRED_SECTIONS=""
case "$TARGET_STATUS" in
  shortlist) REQUIRED_SECTIONS="## Scope|## Files to touch" ;;
  claimed)   REQUIRED_SECTIONS="## Scope|## Files to touch|## Claim comment draft" ;;
  working)   REQUIRED_SECTIONS="## Scope|## Files to touch|## Claim comment draft" ;;
  submitted) REQUIRED_SECTIONS="## PR title|## PR body|## Test results" ;;
  merged)    REQUIRED_SECTIONS="## PR title|## PR body|## Test results" ;;
  *)         REQUIRED_SECTIONS="" ;;  # open, dropped: no body requirements
esac

MISSING_SECTIONS=()
if [[ -n "$REQUIRED_SECTIONS" ]]; then
  IFS='|' read -ra SECTIONS <<< "$REQUIRED_SECTIONS"
  for sec in "${SECTIONS[@]}"; do
    # Match the section header anchored at line start (avoid false positives
    # inside code blocks or quoted text).
    if ! /usr/bin/grep -qE "^${sec}\b" "$CANDIDATE"; then
      MISSING_SECTIONS+=("$sec")
    fi
  done
fi

if [[ "${#MISSING_SECTIONS[@]}" -gt 0 ]]; then
  /usr/bin/printf '[transition] WARN: candidate is missing %d required section(s) for status=%s:\n' \
    "${#MISSING_SECTIONS[@]}" "$TARGET_STATUS" >&2
  for sec in "${MISSING_SECTIONS[@]}"; do
    /usr/bin/printf '[transition]   - %s\n' "$sec" >&2
  done
  /usr/bin/printf '[transition]   (advisory only — see references/candidate-file-format.md;\n' >&2
  /usr/bin/printf '[transition]    backfilled candidates legitimately skip early-stage sections)\n' >&2
  # Log it so audits can see the pattern frequency
  MISSING_JSON=$(/usr/bin/printf '%s\n' "${MISSING_SECTIONS[@]}" | jq -Rsc 'split("\n") | map(select(. != ""))')
  jq --null-input --compact-output --arg ts "$NOW" --arg cand "$CANDIDATE" --arg target "$TARGET_STATUS" \
        --argjson missing "$MISSING_JSON" \
    '{ts: $ts, event: "transition_section_warn",
      details: {candidate: $cand, target_status: $target, missing_sections: $missing}}' \
    >> "$LOG" 2>/dev/null || true
fi

# Run gate-runner
/usr/bin/printf '\n[transition] %s on %s\n' "$ACTION" "$(/usr/bin/basename "$CANDIDATE")" >&2
[[ -n "$DOSSIER" ]] && /usr/bin/printf '[transition]   dossier: %s\n' "$DOSSIER" >&2 || /usr/bin/printf '[transition]   dossier: (none — gates that need it will SKIP)\n' >&2

set +e
# Find gate-runner co-located with this script (works whether invoked from
# the skill's scripts directory).
_TRANSITION_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
GATE_VERDICT=$("${_TRANSITION_DIR}/gate-runner.sh" "$ACTION" "$CANDIDATE" "$DOSSIER")
GATE_EXIT=$?
set -e

# Surface verdict
echo "$GATE_VERDICT"

# Log the transition attempt
jq --null-input --compact-output --arg ts "$NOW" --arg action "$ACTION" --arg cand "$CANDIDATE" --arg exit "$GATE_EXIT" --arg verdict "$GATE_VERDICT" \
  '{ts: $ts, event: "transition_attempt", details: {action: $action, candidate: $cand, gate_exit: $exit | tonumber, gate_verdict: ($verdict | fromjson? // {raw: $verdict})}}' >> "$LOG" 2>/dev/null || true

if [[ "$GATE_EXIT" -ne 0 ]]; then
  /usr/bin/printf '\n[transition] BLOCKED. Resolve the BLOCKers above or use --override-gate.\n\n' >&2
  exit 1
fi

# Update candidate state if not dry-run
if [[ "$DRY_RUN" -eq 0 ]]; then
  # Parse target state from action ("foo→bar" → "bar")
  NEW_STATE="${ACTION##*→}"
  if [[ "$NEW_STATE" != "$ACTION" && -n "$NEW_STATE" ]]; then
    TMP="${CANDIDATE}.tmp.$$"
    /usr/bin/sed "s/^status: .*/status: $NEW_STATE/" "$CANDIDATE" > "$TMP"
    /usr/bin/mv "$TMP" "$CANDIDATE"  # atomic
    /usr/bin/printf '[transition] candidate status → %s\n\n' "$NEW_STATE" >&2

    # Log success
    jq --null-input --compact-output --arg ts "$NOW" --arg action "$ACTION" --arg cand "$CANDIDATE" --arg new_state "$NEW_STATE" \
      '{ts: $ts, event: "transition_committed", details: {action: $action, candidate: $cand, new_state: $new_state}}' >> "$LOG" 2>/dev/null || true
  fi
fi

exit 0
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall