Blueprint Sync

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

When to Use This Skill

Flags

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"

1a. Detect pre-contract records (issue #2868):

Manifests written by blueprint 3.0.0 key generated.rules without .md and carry no content_hash, so Step 2 would report every rule missing. Check first:

bash "${CLAUDE_SKILL_DIR}/../../scripts/migrate-generated-rules-keys.sh" --dry-run

• STATUS=OK → continue to Step 2.
• KEY_MISSING_EXTENSION or RECORD_MISSING_HASH above 0 → WARN in the report with each key_missing_extension / record_missing_hash issue — never list those rules as missing. With --dry-run, stop at the warning and recommend /blueprint:sync. Otherwise run the script without --dry-run: it re-keys to <key>.md and backfills content_hash from the current file with status: "modified", never touching the rule files.
• key_unresolved / key_conflict issues → list them for the user; the script leaves those records untouched.

2. Check each generated rule:

   First resolve the rules directory from the manifest — never hardcode .claude/rules/, or sync looks in the wrong place in every repo that chose an isolated generated_rules_path in /blueprint:init Step 4a (issues #1043, #1675, #2331):

   RULES_DIR=$(jq -r '.structure.generated_rules_path // ".claude/rules/"' docs/blueprint/manifest.json)
   RULES_DIR="${RULES_DIR%/}"
   

   generated.rules is an object map keyed by filename (see blueprint-plugin/schemas/manifest.schema.json), so iterate it with to_entries[]:

   jq -r '(.generated.rules // {}) | to_entries[] | [.key, (.value.content_hash // ""), (.value.source_hash // "")] | @tsv' docs/blueprint/manifest.json
   

   For each entry, {key} is the rule's bare filename including the .md extension, relative to $RULES_DIR. Resolve it as "$RULES_DIR/{key}" — do not append .md, which would look for development.md.md and report every registered rule as missing.

   a. Verify file exists:

   test -f "$RULES_DIR/{key}"
   

   b. Hash current content (bare hex, matching the content_hash the producers write — no sha256: prefix):

   sha256sum "$RULES_DIR/{key}" | 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
   • A record with no source_hash (rules written by /blueprint:init) is never stale — only modified applies

3. Display sync report:

   Generated Content Sync Status
   
   Rules ($RULES_DIR):
   ✅ 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 content_hash to current, mark as acknowledged
   • "Regenerate" → Regenerate this rule from PRDs
   • "View diff" → Show diff then re-ask
   • "Skip" → Continue to next file

6. For stale content, offer options:

   question: "{name} is stale (PRDs have changed). What would you like to do?"
   options:
     - label: "Regenerate from PRDs (Recommended)"
       description: "Update with latest patterns from docs/prds/"
     - label: "Keep current version"
       description: "Mark as current without regenerating"
     - label: "View what changed in PRDs"
       description: "See PRD changes before deciding"
     - label: "Skip this file"
       description: "Leave stale for now"
   

   Based on selection:

   • "Regenerate" → Regenerate this rule from PRDs
   • "Keep" → Update source_hash to current, mark as current
   • "View" → Show PRD diff then re-ask
   • "Skip" → Continue to next file

7. Update manifest after changes:

   • Update content_hash for regenerated files
   • Update source_hash if PRD changes acknowledged
   • Update status field appropriately

8. Final report:

   Sync Complete
   
   Actions taken:
   - testing-strategies.md: Modifications acknowledged
   - implementation-guides.md: Regenerated from PRDs
   
   Current state:
   - 4 generated rules (all current)
   
   Manifest updated.
   

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