blueprint-sync

created	"2025-12-22T00:00:00.000Z"
modified	"2026-07-05T00:00:00.000Z"
reviewed	"2026-05-03T00:00:00.000Z"
description	Check for stale generated content and offer regeneration or promotion. Use when syncing blueprint after PRD changes, or reconciling .claude/rules/ drift.
args	[--dry-run]
argument-hint	--dry-run to preview sync status without modifying files
allowed-tools	Read, Bash, Glob, AskUserQuestion
name	blueprint-sync

Check the status of generated content and offer options for modified or stale files.

When to Use This Skill

Use this skill when...	Use blueprint-promote instead when...
You want to detect stale or modified generated rules/skills	You've decided to keep one specific edited rule (single artifact)
You're reconciling drift between .claude/rules/ and the manifest	You want to acknowledge modifications and stop sync warnings
You want regenerate/promote/keep options for many files at once	Use blueprint-generate-rules instead to (re)generate from PRDs
You preview status with --dry-run before changing anything	Use blueprint-sync-ids instead for ID assignment, not content drift

Flags

Flag	Description
--dry-run	Preview sync status report without interactive prompts or file modifications

Interaction Mode

Before any closing AskUserQuestion menu, resolve the automation config:

bash "${CLAUDE_SKILL_DIR}/../../scripts/get-automation-config.sh"

When EFFECTIVE_INTERACTION_MODE=quiet and this invocation was automation-initiated (autopilot, session bookend, drift-nudge follow-up — not a slash command the user typed), skip closing navigation menus ("what next?" / "create another?" style): apply the safe default and end with a one-line receipt instead. Quiet mode never skips confirmation gates that guard writes — only navigation menus. A direct user invocation always behaves fully interactively (explicit intent overrides quiet; see ADR-0020).

Steps

Purpose:

• Detect when generated skills/commands have been manually modified
• Detect when source PRDs have changed (making generated content stale)
• Offer appropriate actions: regenerate, promote to custom, or keep as-is

1. Read manifest:

   cat docs/blueprint/manifest.json
   

   • Extract generated.rules section
   • If no generated content, report "Nothing to sync"

2. Check each generated rule: For each rule in manifest.generated.rules:

   a. Verify file exists:

   test -f .claude/rules/{name}.md
   

   b. Hash current content:

   sha256sum .claude/rules/{name}.md | cut -d' ' -f1
   

   c. Compare hashes:

   • If content_hash matches → status: current
   • If content_hash differs → status: modified

   d. Check source freshness (for rules from PRDs):

   • Hash current PRD content
   • Compare with source_hash in manifest
   • If differs → status: stale

3. Display sync report:

   Generated Content Sync Status
   
   Rules (.claude/rules/):
   ✅ architecture-patterns.md: Current
   ⚠️ testing-strategies.md: Modified locally
   🔄 implementation-guides.md: Stale (PRDs changed)
   ✅ quality-standards.md: Current
   
   Summary:
   - Current: 3 files
   - Modified: 1 file (user edited)
   - Stale: 1 file (source changed)
   

4. If --dry-run: Output the sync report from Step 3 and exit. Skip all remaining steps.

5. For modified content, offer options:

   question: "{name} has been modified locally. What would you like to do?"
   options:
     - label: "Keep modifications"
       description: "Mark as acknowledged, preserve your changes"
     - label: "Discard modifications (regenerate)"
       description: "Overwrite with fresh generation from PRDs"
     - label: "View diff"
       description: "See what changed before deciding"
     - label: "Skip this file"
       description: "Leave as-is for now"
   

   Based on selection:

   • "Keep modifications" → Update to current, mark as acknowledged

Tips:

• Run /blueprint:sync periodically to check for drift
• Acknowledge modifications you want to keep
• Regenerating will overwrite local changes
• Stale content still works, but may miss new patterns from PRDs