ghm-template-sync

Template Sync

Detect template version drift and migrate to the latest template version.

Workflow

Phase 1: Detect Current State

1. Read .claude/VERSION (if it exists) to get current template version
2. If no VERSION file, check CLAUDE.md frontmatter for template_version
3. If neither exists, assume v1.0.0 (pre-versioning)
4. Report: "Your repo is on template v{X}. Latest is v{Y}."

Phase 2: Diff Against Template

Compare your repo structure against what the current template version expects:

Check for missing files:

• .claude/VERSION
• .claude/domain-profile.yaml
• .claude/hooks/HOOK_CONTRACT.md
• .claude/hooks/context-validation.sh
• .claude/hooks/context-density-gate.sh
• .claude/hooks/sot-update-trigger.sh
• CHANGELOG.md
• MIGRATION.md

Check for stale files (should be removed):

• .claude/hooks/context-validation.py
• .claude/hooks/context-density-gate.py
• .claude/hooks/sot-update-trigger.py
• .claude/agents/HORIZON.md (replaced by subdirectory)
• .claude/agents/STUDIO.md
• .claude/agents/DEVLAB.md
• .claude/agents/METRO.md

Check for structure issues:

• settings.json: Does it use 3-level nesting? Are timeouts in seconds?
• Agent directories: Do horizon/, studio/, devlab/, metro/ subdirectories exist with AGENT.md + MEMORY.md?
• EPIC template: Does it use semantic headers (not numbered)?
• Frontmatter: Do key files have template_version?

Phase 3: Generate Migration Plan

Output a table:

File	Status	Action	Risk
.claude/VERSION	Missing	Copy from template	None
.claude/hooks/*.py	Stale	Delete (replaced by .sh)	None
.claude/agents/HORIZON.md	Stale	Split into horizon/AGENT.md + MEMORY.md	Preserve MEMORY.md content
settings.json	Outdated	Update hook nesting + commands	Check for custom hooks
CLAUDE.md	Missing frontmatter	Add template_version: "3.0.0"	None

Phase 4: Execute Safe Updates

Auto-safe (do without asking):

• Create .claude/VERSION with current template version
• Add template_version frontmatter to files that lack it
• Report what was done

Confirm first (show diff, ask user):

• Update settings.json hook configuration
• Restructure agent files (must preserve MEMORY.md)
• Delete stale Python hooks
• Update EPIC template headers

Never touch (product-specific):

• PRD.md content (only add frontmatter)
• SoT/*.md content
• epics/EPIC-*.md content (only update headers on closed EPICs)
• .claude/agents/*/MEMORY.md content
• README.md content

Phase 5: Verify

After all changes:

1. Test all shell hooks produce valid JSON
2. Verify no Python hooks remain
3. Confirm settings.json uses correct nesting
4. Check agent subdirectories have both AGENT.md and MEMORY.md
5. Report summary of changes made

Version Migration Matrix

From	To	Key Changes
v1.0.0	v2.0.0	Add skills, hooks, agents, SoT standardization
v2.0.0	v3.0.0	Shell hooks, agent subdirs, semantic EPICs, versioning, domain-profile
v1.0.0	v3.0.0	All of the above (cumulative)

Safety Rules

1. NEVER overwrite MEMORY.md -- these contain product-specific agent memory
2. NEVER modify SoT content -- only add section markers or frontmatter
3. NEVER modify PRD.md content -- only add frontmatter version
4. ALWAYS show diff before destructive changes (deletes, restructures)
5. ALWAYS verify hooks work after updating settings.json
6. Commit changes incrementally -- one commit per phase, not one giant commit