Skip to content

Sync Flow

Jump to bottom
Priscila Saboia Moreira edited this page Jul 1, 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: one manifest, three consumer scripts

Since PR #60 (merged 2026-06-28), the sync contract lives in a single file: scripts/lib/template-manifest.sh. scripts/update-from-template.sh, scripts/check-template-version.sh, and scripts/adopt.sh all source it and assemble their working set from its arrays via lw_manifest_assemble_active_files. To add or remove a template-synced file, edit the manifest and nothing else. This page describes the array roles; the file lists themselves are deliberately not duplicated here — the manifest is the source of truth, and the previous version of this page proved that a copied list rots (see Wiki-Corrections-Log).

The six arrays, as of template main @ c19eec8 (2026-07-01):

TEMPLATE_SHARED_INFRA (agent-agnostic core, always synced)

32 files that ship to every derived project regardless of overlay: llm-wiki.md, wiki/init-wiki.sh, the wiki/agents/*.md shared docs, both sync scripts, the feature-flag scripts, the whole scripts/lib/*.sh shared library, features/README.md, and the scripts/wiki-write-protocol/ tree.

TEMPLATE_OVERLAY_CLAUDE / TEMPLATE_OVERLAY_CURSOR (conditional on overlay presence)

The per-agent files (13 Claude Code, 6 Cursor). In update/check the overlay is activated by directory presence on disk (.claude/ or wiki/agents/claude-code/; .cursor/ or wiki/agents/cursor/); in adopt it is activated by the --agent flag.

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

The wiki-* slash commands, skills, and cursor rules (10 files) ship with literal {{REPO_NAME}} tokens that must be substituted by the derived project's $REPO_NAME after copy.

TEMPLATE_HOST_OWNED (template defines the operation, host owns the content)

CLAUDE.md (managed-block), .gitignore (append-only), .claude/settings.json (merge). update-from-template does not touch these at all — .gitignore in particular moved here from the old always-synced list; the post-sync report prints an advisory when the host's .gitignore diverges from the template's, and the host back-ports manually. Adopt uses these entries to seed its default TOUCH grants.

TEMPLATE_ONE_SHOT (consumed by instantiate.sh, never synced)

Documentation-only record: scripts/instantiate.sh (self-deletes after a successful instantiation), CLAUDE.md.template, README.md.template, .claude/settings.json.template, .cursorrules.template. The sync logic does not iterate over this array.

Not on any list

scripts/kg/ (the Knowledge-Graph-Pipeline, shipped in PR #14) exists in the template repo but is not in the manifest's sync arrays. Derived projects therefore do not automatically receive the KG pipeline on update-from-template.sh. The current plan is to ship it as an opt-in feature under features/kg/ (using the feature-flag framework from RFC #13) rather than promoting it to TEMPLATE_SHARED_INFRA.

The footgun (resolved 2026-06-28)

Historically, adding a new template file required updating parallel arrays in both sync scripts (and later a third copy in adopt.sh). Forgetting one was silent: derived projects simply never received the file, while the per-overlay procedures that reference it found a dead reference. PR #1 hit this for both discipline-gates.md and verification-gate.md; Priscila caught it as review point 3. See Lesson-Parallel-File-Drift.

The manifest consolidation (PR #60) closed the class: there is one array set, and two test fixtures lock the contract — scripts/test/tests/unit/manifest-shape/ enforces the cross-array invariants (every path exists in the tree, no double-ownership, every substitute entry contains {{REPO_NAME}}), and scripts/test/tests/smoke/manifest-convergence/ proves adopt and instantiate produce a convergent on-disk file set.

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