Skip to content

Template vs Derived Projects

Jump to bottom
Priscila Saboia Moreira edited this page Jul 1, 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 manifest at scripts/lib/template-manifest.sh. 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 manifest at scripts/lib/template-manifest.sh is the contract: a file not in its sync arrays does not propagate. Adding a new template asset means adding its path to the manifest and nothing else — since PR #60 the sync scripts and adopt.sh all assemble their working set from that single file, and the manifest-shape unit fixture fails if an entry points at a path that does not exist in the tree.

A file that exists in the template but is missing from the manifest is silently invisible to derived projects, while procedures referencing it produce dead links. PR #1's review caught exactly this back when the list was two parallel arrays (see Lesson-Parallel-File-Drift); the manifest consolidation is what retired that failure mode.

See also

Clone this wiki locally