Skip to content

Template vs Derived Projects

Jump to bottom
Chris Sweet edited this page May 20, 2026 · 3 revisions

type: concept up: "Home_llm-wiki-memory-template" tags: [architecture, template]

Template vs Derived Projects

This repository is a template. It ships scaffolding that becomes the wiki-llm pattern in a real project. The distinction between the template and a project instantiated from it is load-bearing for several decisions in the codebase.

What the template ships

  • wiki/ directory containing scaffolding files (agents/, init-wiki.sh) that get copied or referenced by derived projects. The template's own wiki does not live here; this directory is for the scaffolding, not the template's own knowledge base.
  • scripts/instantiate.sh: first-use bootstrap. Substitutes ${REPO_NAME}, ${PROJECT_NAME}, etc. into CLAUDE.md.template and README.md.template, runs init-wiki.sh, then self-deletes.
  • scripts/update-from-template.sh: syncs template improvements into existing derived projects via the ALWAYS_FILES allowlist. See Sync-Flow.
  • Agent overlays under wiki/agents/ (see Agent-Overlays).
  • Two agent-agnostic policy files: wiki/agents/discipline-gates.md and wiki/agents/verification-gate.md. Both apply regardless of which overlay a derived project chose.

What a derived project owns

  • Its own wiki/<repo>.wiki/ sub-repo, scaffolded by init-wiki.sh.
  • Its own CLAUDE.md, generated from CLAUDE.md.template.
  • Its own README.md, generated from README.md.template.
  • Its own slash commands, skills, or rules, copied from the chosen overlay under wiki/agents/<overlay>/.

The two-file rule

Several template assets exist in two parallel files: the canonical content for instantiation, and a snippet for the setup.sh --seed-memory add-to-existing-repo flow.

Canonical (instantiate.sh path) Snippet (setup.sh path)
CLAUDE.md.template wiki/agents/claude-code/templates/claude-md-snippet.md
README.md.template (no parallel; README generation is instantiation-only)

When updating content that lives in a parallel pair, both files must be updated together. This is a known footgun; see Lesson-Parallel-File-Drift.

Why the separation matters

Existing derived projects pull template improvements via update-from-template.sh. The script's ALWAYS_FILES allowlist is the contract: a file not on the list does not propagate. Adding new template assets (e.g., the discipline-gates and verification-gate files introduced in PR #1) requires adding their paths to ALWAYS_FILES in both update-from-template.sh and check-template-version.sh.

A file that exists in the template but is missing from ALWAYS_FILES is silently invisible to derived projects, while procedures referencing it produce dead links. PR #1's review caught exactly this.

See also

Clone this wiki locally