Skip to content

Governance

Jump to bottom
Chris Sweet edited this page May 23, 2026 · 1 revision

type: concept up: "Home_llm-wiki-memory-template" extends: "Template-vs-Derived-Projects" related: "Sync-Flow" tags: [governance, variants, maintenance, architecture]

Governance

How to decide where new functionality belongs as the wiki-llm pattern spreads beyond llm-wiki-memory-template into specialized template variants — and how variants stay in sync with the base over time. Extends the two-layer model in Template-vs-Derived-Projects by introducing a third tier between the base template and an instantiated project: the variant template.

Why this matters

The pattern has begun to proliferate beyond its original scope:

  • Applied-Example-Microelectronics-Tutor-Demo is a derived project, but the tutor-specific scaffolding around it generalized into a sibling template at chrissweet/llm-wiki-tutor-template — a variant that derived projects can instantiate from instead of from the base.
  • Adjacent variants are being scoped (codebase onboarding, grant authoring with Word handlers, multiple SCALE courses).

Without a governance rule, two failure modes appear quickly: feature creep in the base (tutor-specific or grant-specific behavior leaks into the base template, bloating it for users who don't need it), and drift across variants (two variants reimplement the same generic feature in incompatible ways because neither thought to push it upstream). The decision rule below preempts both.

The three tiers

Tier Owns Examples in the current ecosystem
Base template (llm-wiki-memory-template) Truly generic wiki-llm scaffolding usable by any project Wiki schema, init-wiki.sh, /wiki-source slash command, .claude/settings.json security model, agent overlays, instantiate.sh, update-from-template.sh and the ALWAYS_FILES contract
Variant template (e.g. llm-wiki-tutor-template, future onboarding/grant siblings) Behavior contract for a class of derived projects Variant-specific system prompts, launchers, capture/render pipelines, mode-specific CLAUDE.md sections
Derived project Per-instance content Wiki content, ingested source documents, project-specific configuration, custom slash commands not generalizable to the variant

The two-layer model in Template-vs-Derived-Projects compresses variant + base into "the template" and treats them as one. Once a variant exists, the distinction matters.

Where a feature belongs — the placement rule

A new feature gets placed by answering one question first:

Would a project that has nothing to do with this variant's behavior still benefit from this feature?

Answer Tier Examples
Yes — useful for any wiki-llm project Base Wiki schema additions, new agent overlay (Cursor, OpenCode, ...), security-model tightening, knowledge-graph improvements
No — only relevant to this variant's behavior contract Variant Socratic tutor system prompt (tutor variant), word-document edit handlers (grant variant), onboarding-specific capture flows
No — only relevant to one specific instance Derived project Course concept pages, curriculum source PDFs, captured demo dialogs, project-specific student persona text

The phrase to internalize is "behavior contract" — what does this tier do that distinguishes it from the tier above? Anything that defines the contract belongs in that tier; anything below the contract belongs to instances of it.

When to fork a new variant vs add a feature flag

If a new use case can be served by an existing variant with a small switch (env var, CLI flag, optional file), add the flag. If it needs a different behavior contract, fork a new variant.

Concrete criteria for a new variant rather than a feature flag:

  • The system prompt's load-bearing rules would conflict with an existing variant's. Example: a grant-authoring variant wants the assistant to write the document for the user — directly contrary to a tutor variant's "never deliver the answer" rule.
  • The CLAUDE.md "mode" section would mislead a reader about which audience the repo serves.
  • The capture / render or other infrastructure differs in shape, not just content. Example: codebase onboarding may not need recorded MP4s at all — terminal sessions yes, rendered videos probably no.

Concrete criteria for a feature flag rather than a new variant:

  • Same prompt, same launcher, same CLAUDE.md mode, but one knob differs (e.g. a --no-mistake-plant for an author who wants a clean confirmation-only tutor demo).
  • The "differs" lives in a config file or parameterized prompt section, not a fork.

When in doubt: prefer the variant fork over the flag. Flags accumulate; variants stay small and legible.

Rebase discipline (keeping variants synced to the base)

A variant template inherits from the base. The base evolves (new overlays, schema additions, security improvements, KG pipeline changes). Variants should pull those improvements periodically.

The procedure:

  1. Periodically run scripts/update-from-template.sh (or its equivalent) in the variant against the base. The ALWAYS_FILES contract documented in Sync-Flow governs what propagates — generic content is replaced; variant-specific content (the variant's system prompt, custom launchers, mode-specific CLAUDE.md sections) is preserved by virtue of not being on the list.
  2. Resolve conflicts toward the variant's distinguishing layer. If an upstream improvement would erase a variant-specific addition, the variant's addition wins; the upstream improvement gets re-applied around it.
  3. Document each rebase in the variant's log. ## [YYYY-MM-DD] rebase | from base @<sha> with a bullet for each non-trivial conflict.

Variants should not maintain forked copies of files that the base owns. If a base file needs a variant-specific change, that's a signal: either the change belongs upstream (push it back), or the variant needs a new file alongside the base file rather than replacing it.

When a feature graduates from variant to base

A feature that started variant-specific can become general enough to upstream. The trigger:

  • Two or more variants implement essentially the same thing.
  • Or a base-level user (someone not using any variant) asks for it.

When that happens, push the feature upstream to the base template, then delete it from the variants on the next rebase. The variant repo's log entries become the historical record of where the feature originated. The ALWAYS_FILES allowlist gets the new path added at the same time, or the upstream addition is invisible to existing derived projects — same footgun as the one Lesson-Parallel-File-Drift documents.

Ownership and drift detection

Each variant should have a named maintainer responsible for the rebase cadence and the "graduate to base" decisions. Without an owner, drift happens silently — variants reinvent each other's wheels and never feed improvements upstream.

A lightweight drift detection: each variant runs scripts/check-template-version.sh (or equivalent) periodically and reports the result. If three variants are all 50 commits behind base, that's a signal the base has been changing fast and a coordinated catch-up rebase is overdue. This is the same drift dynamic the Sync-Flow page documents between the base and derived projects, escalated one tier.

Open questions

  • Variant discovery. A registry in the base template's README, a tag convention on GitHub, or word-of-mouth? Today: word-of-mouth.
  • Versioning. Do variants pin to a base SHA / tag, or always rebase to base's HEAD? Today: HEAD on update, no formal versioning.
  • Cross-variant features. What if a feature is useful to two variants but not all? Example: the demo capture pipeline from the tutor variant is potentially useful to a codebase-onboarding variant but not to a grant-authoring variant. Today: keep in the variant where it originated; the second variant copies if needed and we revisit if a third variant wants it (the graduation trigger above).

These are worth resolving as the variant population grows beyond two or three.

See also

Clone this wiki locally