Skip to content

me2resh/apexyard / .claude/skills/orbit

Run the opt-in ORBIT planning lifecycle for one managed project without replacing ApexYard governance.

FileKindSize
SKILL.mdskill md27.5 KB
lib/handoff-preflight.shexecutablescript9.2 KB
lib/record-check.shexecutablescript3.5 KB
lib/records-lint.shexecutablescript14.5 KB
lib/refresh-slice-record.shexecutablescript3.4 KB
lib/resolve-project-repo.shexecutablescript2.1 KB
lib/slice-pr-lint.shscript10.6 KB
lib/status-live.shexecutablescript3.4 KB
lib/warn-criterion-shape.shexecutablescript3.3 KB
lib/warn-uncovered-outcomes.shexecutablescript8.2 KB
tests/_lib-fixtures.shexecutablescript8.0 KB
tests/_lib-slice-fixtures.shscript1.8 KB
tests/smoke.shexecutablescript1.3 KB
tests/test_criterion_shape.shexecutablescript3.5 KB
tests/test_handoff_allows_duplicate_prefix_match.shexecutablescript1.9 KB
tests/test_handoff_preflight_happy_path.shexecutablescript1.9 KB
tests/test_handoff_refusal_cli_absent.shexecutablescript1.6 KB
tests/test_handoff_refusal_duplicate_search_fails.shexecutablescript1.5 KB
tests/test_handoff_refusal_duplicate_search_truncated.shexecutablescript2.1 KB
tests/test_handoff_refusal_duplicate_slice.shexecutablescript1.8 KB
tests/test_handoff_refusal_leak_scrub.shexecutablescript4.8 KB
tests/test_handoff_refusal_missing_option_value.shexecutablescript2.4 KB
tests/test_handoff_refusal_slice_id_double_quote.shexecutablescript2.9 KB
tests/test_handoff_refusal_slice_id_newline.shexecutablescript2.8 KB
tests/test_handoff_refusal_validate_fails.shexecutablescript1.4 KB
tests/test_record_check_blank_line.shexecutablescript4.1 KB
tests/test_record_check_change_only.shexecutablescript3.7 KB
tests/test_records_lint_changed_fields.shexecutablescript4.8 KB
tests/test_records_lint_faults.shexecutablescript6.1 KB
tests/test_records_lint_slice_evidence.shscript1.2 KB
tests/test_records_lint_slice_merge_base_drift.shexecutablescript7.2 KB
tests/test_records_lint_slice_provenance.shscript532 B
tests/test_records_lint_slice_scope.shscript1.8 KB
tests/test_records_lint_slice_warn.shscript324 B
tests/test_records_lint_upstream_skip.shscript3.0 KB
tests/test_refresh_slice_record.shscript3.4 KB
tests/test_resolve_project_repo_registry.shexecutablescript4.2 KB
tests/test_slice_pr_proposal.shscript2.9 KB
tests/test_slice_ticket_workflow.shscript1.4 KB
tests/test_status_live_squash_commit.shscript858 B
tests/test_status_live_writes_nothing.shexecutablescript1.9 KB
tests/test_uncovered_outcomes.shscript11.0 KB

lib/handoff-preflight.sh

View on GitHub
#!/usr/bin/env bash
# handoff-preflight.sh — mechanical checks for /orbit handoff (apexyard#1446).
#
# Resolves the Plan, Snapshot and Reconciliation that a slice's `basedOn`
# points to, runs `orbit validate --all`, refuses when an open issue in the
# target repo already carries the exact slice ID, runs
# `orbit sync github --dry-run`, then scrubs the rendered preview for a
# private-portfolio leak. Prints the scrubbed preview JSON on stdout only
# after all five checks pass.
#
# This script never asks for confirmation and never runs the real sync. The
# /orbit handoff flow in SKILL.md shows this script's stdout to the operator,
# asks for a "yes", and only then runs the real `orbit sync github` call
# itself (without --dry-run).
#
# Exit codes:
#   0  the scrubbed preview is printed on stdout
#   10 the ORBIT CLI is absent (ac1-4)
#   11 `orbit validate` failed (ac1-3)
#   12 an open issue in the target repo already carries the exact slice-ID
#      token (a shared word or a prefix does not count)
#   13 a usage error, a Plan/Snapshot/Reconciliation record could not be
#      resolved from the slice's `basedOn`, the dry-run sync failed, or the
#      duplicate-issue search could not be verified (it errored, or did not
#      return a JSON array) — a failed search is never treated as "no
#      duplicate found"
#   14 the leak scrub blocked the rendered preview (ac1-6)
#
# Requires: jq, gh. No network calls other than the read-only
# `gh issue list` duplicate check.

set -u

usage() {
  echo "Usage: handoff-preflight.sh --slice <file> --repo <owner/name> --orbit-root <dir>" >&2
  exit 13
}

slice_file=""
repo=""
orbit_root=""

while [ $# -gt 0 ]; do
  case "$1" in
    --slice)
      [ $# -ge 2 ] || usage
      slice_file="$2"
      shift 2
      ;;
    --repo)
      [ $# -ge 2 ] || usage
      repo="$2"
      shift 2
      ;;
    --orbit-root)
      [ $# -ge 2 ] || usage
      orbit_root="$2"
      shift 2
      ;;
    *)
      usage
      ;;
  esac
done

[ -n "$slice_file" ] && [ -n "$repo" ] && [ -n "$orbit_root" ] || usage
[ -f "$slice_file" ] || { echo "Slice record not found: $slice_file" >&2; exit 13; }

ORBIT_BIN="${ORBIT_BIN:-orbit}"
if ! command -v "$ORBIT_BIN" >/dev/null 2>&1; then
  echo "ORBIT CLI not found. Install orbit-spec (https://github.com/me2resh/orbit-spec) or set ORBIT_BIN to the CLI path." >&2
  exit 10
fi

command -v jq >/dev/null 2>&1 || { echo "jq is required to run the handoff preflight." >&2; exit 13; }
command -v gh >/dev/null 2>&1 || { echo "gh is required to check for a duplicate issue." >&2; exit 13; }

# Resolve where the leak scrub lives, relative to this script's own location
# (.claude/skills/orbit/lib/handoff-preflight.sh -> .claude/hooks/), so a
# sandboxed copy of both files finds the sandboxed scrub, not a real fork's.
script_dir="$(cd "$(dirname "$0")" && pwd)"
hooks_dir="$script_dir/../../../hooks"
if [ ! -d "$hooks_dir" ]; then
  echo "Cannot find .claude/hooks relative to this helper (expected at $hooks_dir)." >&2
  exit 13
fi
hooks_dir="$(cd "$hooks_dir" && pwd)"
leak_scrub="$hooks_dir/check-private-refs-runtime.sh"
[ -f "$leak_scrub" ] || { echo "Cannot find the leak scrub at $leak_scrub." >&2; exit 13; }

slice_id=$(jq -r '.id // empty' "$slice_file")
plan_id=$(jq -r '.planId // empty' "$slice_file")
plan_revision=$(jq -r '.basedOn.planRevision // empty' "$slice_file")
reconciliation_id=$(jq -r '.basedOn.reconciliationId // empty' "$slice_file")

[ -n "$slice_id" ] || { echo "Slice record $slice_file has no id." >&2; exit 13; }
# Byte-level check, not `grep -E '^...$'`: grep -q matches if ANY line of a
# multi-line value matches, so a slice id containing a newline could carry
# one clean line (passing the anchored regex) and one hostile line (e.g. a
# quote or a search qualifier) on a second line, and still pass. `tr -d`
# deletes every byte in [A-Za-z0-9._-] from the whole value in one pass,
# including across embedded newlines; anything left over is disallowed.
# LC_ALL=C so the class means exactly those 64 bytes in every locale.
if [ -z "$slice_id" ] || [ -n "$(printf '%s' "$slice_id" | LC_ALL=C tr -d 'A-Za-z0-9._-')" ]; then
  echo "Slice id '$slice_id' contains characters outside [A-Za-z0-9._-]; refusing to build a search query from it." >&2
  exit 13
fi
[ -n "$plan_id" ] && [ -n "$plan_revision" ] || { echo "Slice record $slice_file has no basedOn.planRevision for $plan_id." >&2; exit 13; }
[ -n "$reconciliation_id" ] || { echo "Slice record $slice_file has no basedOn.reconciliationId." >&2; exit 13; }

plan_file=""
for candidate in "$orbit_root"/plans/*.json; do
  [ -f "$candidate" ] || continue
  cid=$(jq -r '.id // empty' "$candidate" 2>/dev/null)
  crev=$(jq -r '.revision // empty' "$candidate" 2>/dev/null)
  if [ "$cid" = "$plan_id" ] && [ "$crev" = "$plan_revision" ]; then
    plan_file="$candidate"
    break
  fi
done
[ -n "$plan_file" ] || { echo "No Plan record matches $plan_id revision $plan_revision under $orbit_root/plans." >&2; exit 13; }

reconciliation_file=""
for candidate in "$orbit_root"/reconciliations/*.json; do
  [ -f "$candidate" ] || continue
  cid=$(jq -r '.id // empty' "$candidate" 2>/dev/null)
  if [ "$cid" = "$reconciliation_id" ]; then
    reconciliation_file="$candidate"
    break
  fi
done
[ -n "$reconciliation_file" ] || { echo "No Reconciliation record matches $reconciliation_id under $orbit_root/reconciliations." >&2; exit 13; }

snapshot_id=$(jq -r '.projectSnapshotId // empty' "$reconciliation_file")
[ -n "$snapshot_id" ] || { echo "Reconciliation record $reconciliation_file has no projectSnapshotId." >&2; exit 13; }

snapshot_file=""
for candidate in "$orbit_root"/snapshots/*.json; do
  [ -f "$candidate" ] || continue
  cid=$(jq -r '.id // empty' "$candidate" 2>/dev/null)
  if [ "$cid" = "$snapshot_id" ]; then
    snapshot_file="$candidate"
    break
  fi
done
[ -n "$snapshot_file" ] || { echo "No Snapshot record matches $snapshot_id under $orbit_root/snapshots." >&2; exit 13; }

# 1 (CLI check) already passed above (command -v "$ORBIT_BIN").

# 2. Validate.
validate_output=$("$ORBIT_BIN" validate --all --root "$orbit_root" 2>&1)
validate_rc=$?
if [ "$validate_rc" -ne 0 ]; then
  echo "orbit validate failed: $validate_output" >&2
  exit 11
fi

# 3. Duplicate check — exact backtick-quoted slice-ID token, fail closed.
dup_stderr=$(mktemp "${TMPDIR:-/tmp}/orbit-handoff-dup.XXXXXX") || {
  echo "Cannot create a temp file for the duplicate-issue check." >&2
  exit 13
}
duplicates_json=$(gh issue list --repo "$repo" --state open --search "\"$slice_id\" in:body" --limit 200 --json number,body 2>"$dup_stderr")
dup_rc=$?
dup_err=$(cat "$dup_stderr" 2>/dev/null)
rm -f "$dup_stderr"
if [ "$dup_rc" -ne 0 ]; then
  echo "Cannot verify whether an open issue in $repo already carries slice ID $slice_id: gh issue list failed: $dup_err" >&2
  exit 13
fi
if ! printf '%s' "$duplicates_json" | jq -e 'type == "array"' >/dev/null 2>&1; then
  echo "Cannot verify whether an open issue in $repo already carries slice ID $slice_id: gh issue list did not return a JSON array." >&2
  exit 13
fi
raw_count=$(printf '%s' "$duplicates_json" | jq 'length' 2>/dev/null)
if [ "$raw_count" = "200" ]; then
  echo "Cannot verify whether an open issue in $repo already carries slice ID $slice_id: the search returned 200 results, its configured limit, and may be cut off." >&2
  exit 13
fi
token='`'"$slice_id"'`'
dup_count=$(printf '%s' "$duplicates_json" | jq --arg tok "$token" '[.[] | select((.body // "") | contains($tok))] | length' 2>/dev/null)
if [ -z "$dup_count" ]; then
  echo "Cannot verify whether an open issue in $repo already carries slice ID $slice_id: could not parse the search result." >&2
  exit 13
fi
if [ "$dup_count" != "0" ]; then
  echo "An open issue in $repo already carries slice ID $slice_id (exact token match). Refusing to file a duplicate." >&2
  exit 12
fi

# 4. Dry-run preview. Stderr is left to inherit (not captured), so a CLI
# warning cannot land inside $preview and corrupt the JSON.
preview=$("$ORBIT_BIN" sync github --dry-run \
  --plan "$plan_file" --snapshot "$snapshot_file" \
  --reconciliation "$reconciliation_file" --slice "$slice_file" \
  --repo "$repo")
preview_rc=$?
if [ "$preview_rc" -ne 0 ]; then
  echo "orbit sync github --dry-run failed (see the CLI's own error above)." >&2
  exit 13
fi

title=$(printf '%s' "$preview" | jq -r '.title // empty')
body=$(printf '%s' "$preview" | jq -r '.body // empty')
if [ -z "$title" ] && [ -z "$body" ]; then
  echo "orbit sync github --dry-run returned neither a title nor a body to scrub." >&2
  exit 13
fi
case "$title" in
  '[Slice] '*) : ;;
  *)
    echo "orbit sync github --dry-run did not return a [Slice] issue title." >&2
    exit 13 ;;
esac

# 5. Leak scrub. Scrub the PLAIN-TEXT title/body (via jq -r), not the raw
# JSON: in JSON a newline is the two characters \n, so a name at the start
# of a body line is preceded by "n", not a real newline, and the scrub's
# word-boundary rule misses it.
body_file=$(mktemp "${TMPDIR:-/tmp}/orbit-handoff-body.XXXXXX") || {
  echo "Cannot create a temp file for the leak scrub." >&2
  exit 13
}
printf '%s\n' "$body" > "$body_file"

scrub_output=$("$leak_scrub" "$repo" "$title" "$body_file" 2>&1)
scrub_rc=$?
rm -f "$body_file"
if [ "$scrub_rc" -ne 0 ]; then
  printf '%s\n' "$scrub_output" >&2
  echo "The leak scrub blocked the handoff preview for slice $slice_id." >&2
  exit 14
fi

printf '%s\n' "$preview"
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall