-
Notifications
You must be signed in to change notification settings - Fork 2
Sync Flow
type: concept up: "Template-vs-Derived-Projects" extends: "Template-vs-Derived-Projects" tags: [sync, maintenance]
How template improvements propagate from the template repository to existing derived projects.
scripts/update-from-template.sh and scripts/check-template-version.sh both maintain an allowlist named ALWAYS_FILES. A file's path is on the list iff the template wants that file synced into derived projects.
Files on the list include:
wiki/init-wiki.shwiki/agents/<overlay>/setup.sh-
wiki/agents/<overlay>/templates/*.md(per-overlay templates) -
wiki/agents/discipline-gates.mdandwiki/agents/verification-gate.md(agent-agnostic policy) -
.claude/commands/wiki-*.mdand.claude/skills/wiki-*.md(Claude Code surfaces) -
.cursor/rules/wiki-*.mdc(Cursor surfaces) -
scripts/kg/*.sh(KG pipeline)
Files not on the list, deliberately:
-
CLAUDE.md.templateandREADME.md.template: one-shot inputs toinstantiate.sh. After instantiation the derived project ownsCLAUDE.mdandREADME.mddirectly; the template never tries to merge changes into them retroactively. -
scripts/instantiate.sh: a one-shot file that self-deletes after a successful instantiation. Excluded from sync explicitly.
Adding a new template file requires adding its path to ALWAYS_FILES in both sync scripts. Forgetting this is silent: derived projects simply never receive the file, while the per-overlay procedures that reference it find a dead reference. PR #1 hit this for both discipline-gates.md and verification-gate.md; Priscila caught it as review point 3 and the fix landed before merge. See Lesson-Parallel-File-Drift.
scripts/check-template-version.sh compares a derived project's last-synced template commit against the template's current main. The .llm-wiki-template-log.md file in the derived project records sync history. Keeping this file in git gives a permanent trail; the template's .gitignore makes it commit-or-not at the project's discretion.
update-from-template.sh runs in the derived project's main repo, not the wiki sub-repo. It does not push; the derived project decides when and whether to publish the sync as a commit.