mattgierhart/PRD-driven-context-engineering / .claude/skills/ghm-template-sync
ghm-template-sync
VerifiedDetect template version drift and guide migration to the latest template version. Compares current repo against the template, identifies what's outdated, and automates safe updates while protecting product-specific content. Triggers on requests to sync with template, update template version, check for template drift, or when user asks "sync template", "update to v3", "template drift", "check template version".
Template Sync
Detect template version drift and migrate to the latest template version.
Workflow
Phase 1: Detect Current State
- Read
.claude/VERSION(if it exists) to get current template version - If no VERSION file, check
CLAUDE.mdfrontmatter fortemplate_version - If neither exists, assume v1.0.0 (pre-versioning)
- 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.shCHANGELOG.mdMIGRATION.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 withAGENT.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/VERSIONwith current template version - Add
template_versionfrontmatter to files that lack it - Report what was done
Confirm first (show diff, ask user):
- Update
settings.jsonhook configuration - Restructure agent files (must preserve MEMORY.md)
- Delete stale Python hooks
- Update EPIC template headers
Never touch (product-specific):
PRD.mdcontent (only add frontmatter)SoT/*.mdcontentepics/EPIC-*.mdcontent (only update headers on closed EPICs).claude/agents/*/MEMORY.mdcontentREADME.mdcontent
Phase 5: Verify
After all changes:
- Test all shell hooks produce valid JSON
- Verify no Python hooks remain
- Confirm
settings.jsonuses correct nesting - Check agent subdirectories have both AGENT.md and MEMORY.md
- 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
- NEVER overwrite MEMORY.md -- these contain product-specific agent memory
- NEVER modify SoT content -- only add section markers or frontmatter
- NEVER modify PRD.md content -- only add frontmatter version
- ALWAYS show diff before destructive changes (deletes, restructures)
- ALWAYS verify hooks work after updating settings.json
- Commit changes incrementally -- one commit per phase, not one giant commit
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |