Skip to content

Sync Flow

Jump to bottom
Chris Sweet edited this page May 31, 2026 · 8 revisions

type: concept up: "Template-vs-Derived-Projects" extends: "Template-vs-Derived-Projects" tags: [sync, maintenance]

Sync Flow

How template improvements propagate from the template repository to existing derived projects.

The contract: five arrays in two sync scripts

scripts/update-from-template.sh and scripts/check-template-version.sh both maintain the same five arrays, byte-for-byte aligned with each other. Together they define what gets synced into derived projects, what gets re-substituted after sync, and what is deliberately not synced. The arrays as currently in main:

ALWAYS_FILES (agent-agnostic core, always synced)

Eight files that ship to every derived project regardless of overlay:

  • llm-wiki.md
  • wiki/init-wiki.sh
  • wiki/agents/README.md
  • wiki/agents/discipline-gates.md
  • wiki/agents/verification-gate.md
  • scripts/update-from-template.sh
  • scripts/check-template-version.sh
  • .gitignore

CLAUDE_FILES (conditional on Claude Code presence)

Synced only if the derived project has .claude/ or wiki/agents/claude-code/:

  • .claude/commands/wiki-experiment.md, wiki-source.md, wiki-lint.md
  • .claude/skills/wiki-experiment.md, wiki-source.md, wiki-lint.md
  • wiki/agents/claude-code/setup.sh
  • wiki/agents/claude-code/README.md
  • wiki/agents/claude-code/templates/claude-md-snippet.md
  • wiki/agents/claude-code/templates/memory-seed.md
  • wiki/agents/claude-code/templates/session-start-hook.sh

CURSOR_FILES (conditional on Cursor presence)

Synced only if the derived project has .cursor/ or wiki/agents/cursor/:

  • .cursor/rules/wiki-as-memory.mdc, wiki-experiment.mdc, wiki-source.mdc, wiki-lint.mdc
  • wiki/agents/cursor/setup.sh
  • wiki/agents/cursor/README.md

ONE_SHOT_FILES (consumed by instantiate.sh, never re-synced)

Listed for documentation only; the sync logic does not iterate over this array:

  • scripts/instantiate.sh (self-deletes after a successful instantiation)
  • CLAUDE.md.template and README.md.template (consumed and removed by instantiate.sh; the derived project owns its CLAUDE.md and README.md directly thereafter)
  • .claude/settings.json.template
  • .cursorrules.template

SUBSTITUTE_FILES (require {{REPO_NAME}} substitution after sync)

The wiki-* slash commands, skills, and cursor rules all ship with literal {{REPO_NAME}} tokens that must be substituted by the derived project's $REPO_NAME after pulling from template/main:

  • .claude/commands/wiki-experiment.md, wiki-source.md, wiki-lint.md
  • .claude/skills/wiki-experiment.md, wiki-source.md, wiki-lint.md
  • .cursor/rules/wiki-as-memory.mdc, wiki-experiment.mdc, wiki-source.mdc, wiki-lint.mdc

Not on any list

scripts/kg/ does not exist in the template repo on main; the Knowledge-Graph-Pipeline page that describes it is aspirational (see Implementation-Status). When and if the pipeline ships, its files will be added to ALWAYS_FILES in both sync scripts; until then there is nothing to sync.

The footgun

Adding a new template file requires adding its path to the appropriate array 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.

Version stamping

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.

Push policy

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.

See also

Clone this wiki locally