scaffold-sync

Scaffold Sync Skill

Pull selective scaffold updates from the installed Hakuto plugin into an existing site. The skill is interactive and report-first — every change is shown to the user and applied only on explicit per-file approval. State is persisted in .hakuto-sync.json at the site root so each run only considers drift since the last sync.

Run when the user says any of:

• "Sync scaffold"
• "Check for scaffold updates"
• "Pull scaffold changes"
• "Update scaffold"
• "What's new in the scaffold"
• "Is my scaffold current?"

---

Execution Flow

1. Locate upstream

Resolve the plugin scaffold:

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:?run scaffold-sync from a Hakuto plugin context (CLAUDE_PLUGIN_ROOT not set)}"
SCAFFOLD="${PLUGIN_ROOT}/scaffold"
test -d "$SCAFFOLD" || { echo "ERROR: $SCAFFOLD missing — plugin install is incomplete." >&2; exit 1; }

If CLAUDE_PLUGIN_ROOT is unset or scaffold/ is missing, stop with a one-line error. Do not attempt fallbacks.

2. Resolve current upstream identity

Try git first, fall back to a content hash:

if git -C "$PLUGIN_ROOT" rev-parse --git-dir >/dev/null 2>&1; then
  CURRENT_SHA=$(git -C "$PLUGIN_ROOT" rev-parse HEAD)
  CURRENT_METHOD="git"
else
  # Stable content hash of the scaffold tree (excludes generated/state dirs)
  CURRENT_SHA=$(find "$SCAFFOLD" -type f \
    -not -path '*/node_modules/*' \
    -not -path '*/.astro/*' \
    -not -path '*/dist/*' \
    -not -path '*/.wrangler/*' \
    -not -path '*/.git/*' \
    | sort | xargs sha256sum | sha256sum | awk '{print $1}')
  CURRENT_METHOD="content-hash"
fi

Record both CURRENT_SHA and CURRENT_METHOD for the state file.

Also read the current plugin version from ${PLUGIN_ROOT}/.claude-plugin/plugin.json:

CURRENT_PLUGIN_VERSION=$(jq -r '.version // "unknown"' "${PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null || echo "unknown")

Record CURRENT_PLUGIN_VERSION for the state file and migration report.

3. Read site state