Skip to content

Junhanliu-dev/espalier-engineering / skills/espalier-init

espalier-init

Verified

Analyze any existing codebase, discover its patterns and best practices, and generate an Espalier structure (rules, skills, wiki, pipeline) so AI coders produce code matching that project's language and conventions. Greenfield repos take the two-pass Decide-Then-Bind path (/espalier-map charts the conventions, init binds them); boilerplate repos run init normally, then map the product. Wires into Claude Code, Codex, and/or GitHub Copilot (.claude/, .agents/skills/ + .codex/, .github/).

FileKindSize
SKILL.mdskill md43.5 KB
hook-templates/check-layer-boundaries-go.shscript665 B
hook-templates/check-layer-boundaries-python.shscript821 B
hook-templates/check-layer-boundaries-typescript.shscript1.6 KB
hook-templates/copilot-hook-adapter.shscript2.4 KB
hook-templates/drift-detect.shscript5.7 KB
hook-templates/drift-helpers.shscript56.4 KB
hook-templates/espalier-outside.shexecutablescript28.8 KB
hook-templates/espalier-pr.shexecutablescript43.2 KB
hook-templates/espalier-stats.shexecutablescript27.3 KB
hook-templates/lookup-helpers.shscript9.5 KB
hook-templates/map-guard.shexecutablescript3.9 KB
hook-templates/maprun-dispatch.shexecutablescript21.0 KB
hook-templates/maprun-integration.shexecutablescript3.4 KB
hook-templates/maprun-merge.shexecutablescript2.9 KB
hook-templates/maprun-pr.shexecutablescript12.8 KB
hook-templates/maprun-verify.shexecutablescript5.0 KB
hook-templates/maprun.pyscript65.6 KB
hook-templates/parse-drift-blocks.pyscript1.1 KB
hook-templates/post-edit-wrapper.shscript2.0 KB
hook-templates/post-merge-backlink.shscript2.2 KB
hook-templates/pre-push-gate-wrapper.shscript3.0 KB
hook-templates/pre-push-gate.shscript18.1 KB
hook-templates/rebuild-commit-index.shscript2.6 KB
references/discovery-checklist.mdmarkdown18.5 KB
references/validation.mdmarkdown16.7 KB
references/wiki-templates.mdmarkdown710 B
references/wiring.mdmarkdown13.5 KB
templates/agent.mdmarkdown3.7 KB
templates/agents/harness-coder.mdmarkdown33.9 KB
templates/agents/harness-reviewer.mdmarkdown25.1 KB
templates/agents/harness-security.mdmarkdown14.0 KB
templates/agents/modes/fix-round.mdmarkdown3.0 KB
templates/agents/modes/re-review.mdmarkdown5.3 KB
templates/agents/modes/repo-audit.mdmarkdown2.8 KB
templates/agents/modes/simplification.mdmarkdown7.0 KB
templates/agents/modes/stage6-abuse-coverage.mdmarkdown1.3 KB
templates/agents/modes/wiki-sweep.mdmarkdown5.6 KB
templates/pipeline.mdmarkdown18.9 KB
templates/rules/coding-standards.mdmarkdown3.2 KB
templates/rules/development-process.mdmarkdown3.2 KB
templates/rules/engineering-structure.mdmarkdown1008 B
templates/rules/production-standards.mdmarkdown5.8 KB
templates/rules/security-standards.mdmarkdown5.6 KB
templates/scout-prompts.mdmarkdown9.0 KB
templates/skills/espalier-ask.mdmarkdown6.4 KB
templates/skills/espalier-audit.mdmarkdown10.0 KB
templates/skills/espalier-coding-references/platform-native.mdmarkdown9.4 KB
templates/skills/espalier-coding-spec.mdmarkdown496 B
templates/skills/espalier-coding.mdmarkdown4.0 KB
templates/skills/espalier-doctor.mdmarkdown8.0 KB
templates/skills/espalier-fix.mdmarkdown77.5 KB
templates/skills/espalier-grill.mdmarkdown21.5 KB
templates/skills/espalier-map.mdmarkdown20.0 KB
templates/skills/espalier-maprun.mdmarkdown31.1 KB
templates/skills/espalier-prune.mdmarkdown13.0 KB
templates/skills/espalier-repot.mdmarkdown7.6 KB
templates/skills/espalier-requirements.mdmarkdown4.7 KB
templates/skills/espalier-review.mdmarkdown4.5 KB
templates/skills/espalier-security.mdmarkdown5.6 KB
templates/skills/espalier-simplify.mdmarkdown25.0 KB
templates/skills/espalier-stages/1-2-requirements.mdmarkdown7.6 KB
templates/skills/espalier-stages/3-coding.mdmarkdown15.0 KB
templates/skills/espalier-stages/4-panel.mdmarkdown14.3 KB
templates/skills/espalier-stages/5-6-contract.mdmarkdown10.3 KB
templates/skills/espalier-stages/7-10-delivery.mdmarkdown16.8 KB
templates/skills/espalier-stages/simple.mdmarkdown14.0 KB
templates/skills/espalier-testing.mdmarkdown2.9 KB
templates/skills/espalier.mdmarkdown27.7 KB

hook-templates/lookup-helpers.sh

View on GitHub
#!/bin/bash
# Reverse-lookup helpers for /espalier-fix Stage 0.
# Sourced (not executed) by the skill. All functions are pure shell so they
# can run in any POSIX-compatible environment.
#
# Provides:
#   _push_entry slug sha role lookup   — accumulate per-frame caused_by entries
#   _push_note_entry "<text>"          — append a `- note: ...` overflow row
#   _dedupe_entries_preserve_primary   — drop dup slugs; primary wins over call_path
#   _fuzzy_file_overlap_match <sha>    — fuzzy slug lookup by file-overlap heuristic
#   _cache_append sha slug kind        — idempotent write to espalier/.commit-index.tsv
#   _maybe_warn_slow_scan <start_ns>   — warn (and maybe auto-build cache) if scan exceeded threshold
#   _prompt_user_for_merge_decision    — fix-time fallback prompt (decision = ask-later)

# Per-fix accumulators. Caller must reset these before Stage 0.
ENTRIES_SLUG=()
ENTRIES_SHA=()
ENTRIES_ROLE=()
ENTRIES_LOOKUP=()
ENTRIES_NOTES=()

_push_entry() {
  ENTRIES_SLUG+=("$1")
  ENTRIES_SHA+=("$2")
  ENTRIES_ROLE+=("$3")
  ENTRIES_LOOKUP+=("$4")
}

_push_note_entry() {
  ENTRIES_NOTES+=("$1")
}

# Dedupe by slug, preserving "primary" over "call_path" when both exist.
# Same-slug-same-role duplicates resolved by keeping the earlier occurrence.
# Operates in place on the ENTRIES_* arrays.
#
# O(N²) worst case (nested loop with early-break) — fine at the Stage 0 fan-out
# cap of 5. C-style for loops + cached array accesses keep per-call overhead under 1ms.
_dedupe_entries_preserve_primary() {
  local -a OUT_SLUG=() OUT_SHA=() OUT_ROLE=() OUT_LOOKUP=()
  local i j keep n=${#ENTRIES_SLUG[@]}
  local i_slug i_role j_slug j_role

  for ((i = 0; i < n; i++)); do
    i_slug="${ENTRIES_SLUG[$i]}"
    i_role="${ENTRIES_ROLE[$i]}"
    keep="yes"
    for ((j = 0; j < n; j++)); do
      [ "$i" = "$j" ] && continue
      j_slug="${ENTRIES_SLUG[$j]}"
      [ "$i_slug" != "$j_slug" ] && continue
      j_role="${ENTRIES_ROLE[$j]}"

      # Drop this entry if:
      #   (a) we are call_path and there's a primary for the same slug, OR
      #   (b) same role and we are the later occurrence (i > j).
      if { [ "$i_role" = "call_path" ] && [ "$j_role" = "primary" ]; } \
         || { [ "$i_role" = "$j_role" ] && [ "$i" -gt "$j" ]; }; then
        keep="no"; break
      fi
    done
    if [ "$keep" = "yes" ]; then
      OUT_SLUG+=("$i_slug")
      OUT_SHA+=("${ENTRIES_SHA[$i]}")
      OUT_ROLE+=("$i_role")
      OUT_LOOKUP+=("${ENTRIES_LOOKUP[$i]}")
    fi
  done

  ENTRIES_SLUG=("${OUT_SLUG[@]}")
  ENTRIES_SHA=("${OUT_SHA[@]}")
  ENTRIES_ROLE=("${OUT_ROLE[@]}")
  ENTRIES_LOOKUP=("${OUT_LOOKUP[@]}")
}

# _fuzzy_scan SHA [MAX_AGE_DAYS] — core of the fuzzy overlap heuristic: find
# the Espalier change whose Commits table has the largest overlap of file
# paths with this SHA's tree. Threshold 50%. Sets globals (no stdout):
#   FUZZY_SLUG        slug ("feat/foo") or "" when below threshold
#   FUZZY_BEST_STATE  matched pipeline-state.md path or ""
#   FUZZY_BEST_COUNT  matched-file count of the winner
#   FUZZY_TOTAL       file count of the SHA's tree
# MAX_AGE_DAYS (optional) skips candidates whose state file is older — the
# post-merge backlink hook passes 30 so ancient changes never steal a match.
_fuzzy_scan() {
  local SHA="$1" MAX_AGE_DAYS="${2:-}"
  local FILES BEST_STATE="" BEST_COUNT=0 TOTAL THRESHOLD COUNT f state
  local NOW MTIME AGE_DAYS
  FUZZY_SLUG=""
  FUZZY_BEST_STATE=""
  FUZZY_BEST_COUNT=0
  FUZZY_TOTAL=0

  FILES=$(git diff-tree --no-commit-id --name-only -r "$SHA" 2>/dev/null)
  [ -z "$FILES" ] && return 0
  NOW=$(date +%s)

  for state in espalier/changes/*/*/pipeline-state.md; do
    [ -f "$state" ] || continue
    case "$state" in *_template*) continue ;; esac

    if [ -n "$MAX_AGE_DAYS" ]; then
      if [ "$(uname)" = "Darwin" ]; then
        MTIME=$(stat -f %m "$state" 2>/dev/null)
      else
        MTIME=$(stat -c %Y "$state" 2>/dev/null)
      fi
      [ -z "$MTIME" ] && continue
      AGE_DAYS=$(( (NOW - MTIME) / 86400 ))
      [ "$AGE_DAYS" -gt "$MAX_AGE_DAYS" ] && continue
    fi

    COUNT=0
    # while-read (not `for f in $FILES`) so paths with spaces stay whole.
    # Match a whole-path token in a Commits-table cell, not a bare substring —
    # else `a.ts` spuriously matches `a.tsx` / `dir/a.ts.map` and inflates overlap.
    # The sed class escapes EVERY ERE metachar — including ()+?{}| — so a path
    # like app/(dashboard)/page.tsx matches itself, not a regex group.
    while IFS= read -r f; do
      [ -z "$f" ] && continue
      grep -qE "(^|[^[:alnum:]_./-])$(printf '%s' "$f" | sed 's/[.[\*^$()+?{}|/]/\\&/g')([^[:alnum:]_./-]|$)" "$state" 2>/dev/null \
        && COUNT=$((COUNT + 1))
    done <<EOF
$FILES
EOF
    if [ "$COUNT" -gt "$BEST_COUNT" ]; then
      BEST_COUNT=$COUNT
      BEST_STATE=$state
    fi
  done

  TOTAL=$(echo "$FILES" | wc -l | tr -d ' ')
  THRESHOLD=$(( (TOTAL + 1) / 2 ))
  FUZZY_TOTAL=$TOTAL
  if [ "$BEST_COUNT" -ge "$THRESHOLD" ] && [ -n "$BEST_STATE" ]; then
    FUZZY_BEST_STATE=$BEST_STATE
    FUZZY_BEST_COUNT=$BEST_COUNT
    FUZZY_SLUG=$(echo "$BEST_STATE" | sed 's|espalier/changes/||; s|/pipeline-state.md||')
  fi
}

# Fuzzy: stdout wrapper around _fuzzy_scan — slug ("feat/foo") or empty string.
# Used by the /espalier-fix Stage 0 Layer 3 fallback when no squash hook
# recorded the mapping. Optional second arg = MAX_AGE_DAYS (see _fuzzy_scan).
_fuzzy_file_overlap_match() {
  _fuzzy_scan "$1" "${2:-}"
  [ -n "$FUZZY_SLUG" ] && echo "$FUZZY_SLUG"
  return 0
}

# Append one row to reverse-lookup cache, idempotent (skip if SHA+kind already present).
_cache_append() {
  local SHA="$1" SLUG="$2" KIND="$3"
  local CACHE="espalier/.commit-index.tsv"

  [ -z "$SHA" ] || [ -z "$SLUG" ] && return 0
  [ ! -f "$CACHE" ] && touch "$CACHE"

  grep -qE "^${SHA}	[^	]+	${KIND}	" "$CACHE" 2>/dev/null && return 0
  printf '%s\t%s\t%s\t%s\n' "$SHA" "$SLUG" "$KIND" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$CACHE"
}

# Warn if scan exceeded threshold; auto-build cache on first cold trigger.
# Argument: scan start time. Format depends on platform — caller used:
#   START=$(date +%s%N 2>/dev/null || date +%s)
# We tolerate both ns (Linux) and second (BSD) resolutions.
_maybe_warn_slow_scan() {
  local START="$1"
  local END THRESHOLD_MS DURATION_MS CHANGE_COUNT

  # ESPALIER_CACHE_THRESHOLD_MS preferred; HARNESS_CACHE_THRESHOLD_MS honored for legacy callers.
  THRESHOLD_MS="${ESPALIER_CACHE_THRESHOLD_MS:-${HARNESS_CACHE_THRESHOLD_MS:-1000}}"
  [ "$THRESHOLD_MS" = "0" ] && return 0

  END=$(date +%s%N 2>/dev/null || date +%s)

  # Strip any literal "%N" (BSD date doesn't support %N — returns "1715000000%N").
  # After strip, values are either:
  #   ns precision  → 19 digits (Linux GNU date)
  #   s precision   → 10 digits (BSD/macOS or fallback `date +%s`)
  START=$(echo "$START" | sed 's/[^0-9]//g')
  END=$(echo   "$END"   | sed 's/[^0-9]//g')

  if [ "${#START}" -ge 16 ]; then
    # nanosecond precision — divide by 1e6 to get ms
    DURATION_MS=$(( (END - START) / 1000000 ))
  else
    # second precision — multiply by 1000 to get ms
    DURATION_MS=$(( (END - START) * 1000 ))
  fi

  [ "$DURATION_MS" -lt "$THRESHOLD_MS" ] && return 0

  CHANGE_COUNT=$(find espalier/changes -mindepth 3 -maxdepth 3 -name pipeline-state.md 2>/dev/null | wc -l | tr -d ' ')
  echo "WARNING: reverse-lookup scan took ${DURATION_MS}ms across ${CHANGE_COUNT} changes." >&2

  if [ ! -f "espalier/.commit-index.tsv" ]; then
    echo "Building reverse-lookup cache automatically (one-time)..." >&2
    if [ -x "espalier/hooks/rebuild-commit-index.sh" ]; then
      bash espalier/hooks/rebuild-commit-index.sh
      echo "Cache built. Future lookups will be O(1)." >&2
    else
      echo "Cache builder not found at espalier/hooks/rebuild-commit-index.sh — skipping auto-build." >&2
    fi
  else
    echo "Cache exists but scan still triggered (likely missed entries). Consider:" >&2
    echo "  /espalier-fix --rebuild-index   # full rebuild from pipeline-state.md files" >&2
  fi
}

# Fix-time prompt (only fires when DECISION=ask-later). Writes user's choice
# to espalier/.merge-hook-decision, then caller re-reads + re-loops the SHA.
# This is the rescue path for when init-time decision was deferred. After this
# fires once, all future invocations are silent.
_prompt_user_for_merge_decision() {
  cat >&2 << 'EOF'

Heads up — first fix in this repo. Need to decide one thing.

This repo's merge strategy affects bug-to-commit traceability.

Options (write your choice to espalier/.merge-hook-decision):

  not-needed    — Repo uses rebase or merge-commit; SHAs preserved on main
  installed     — Install post-merge git hook to record squash mappings (recommended for squash repos)
  fuzzy-allowed — No hook; allow fuzzy file-overlap match at fix-time
  skip-only     — No hook, no fuzzy; mark unknown_squash and continue (safest)
  never-ask     — Same as skip-only, silent forever

EOF

  # In an interactive skill, the orchestrator calls this and then uses
  # AskUserQuestion to capture the choice. In a non-interactive run, default
  # to skip-only to avoid hanging. ESPALIER_NONINTERACTIVE preferred;
  # HARNESS_NONINTERACTIVE honored for legacy callers.
  if [ -z "${ESPALIER_NONINTERACTIVE:-${HARNESS_NONINTERACTIVE:-}}" ]; then
    # Placeholder — actual espalier-fix skill uses AskUserQuestion and writes the file.
    # If you're running this directly, edit the decision file by hand:
    #   echo "fuzzy-allowed" > espalier/.merge-hook-decision
    :
  else
    echo "skip-only" > espalier/.merge-hook-decision
    echo "Non-interactive mode: defaulted to skip-only." >&2
  fi
}
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall