mattgierhart/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