Skip to content

ADR-0021: {{PROJECT_NAME}} is a live project and the canonical template source

Guide

ADR-0021: {{PROJECT_NAME}} is a live project and the canonical template source

  • Status: Accepted · Date: 2026-06-02 · Approved by: {{PRINCIPAL_NAME}}
  • Supersedes: the governance conflict between ADR-0010 and ADR-0011

Context

ADR-0010 declared this repo a neutral template. ADR-0011 superseded it, accepting this repo as a real instantiated project named {{PROJECT_NAME}}. However ADR-0011 left open how future repos are instantiated: it said “future forks use TEMPLATE.md” but did not formally ratify the dual-use model or resolve the governance question of whether {{PROJECT_NAME}} is still the template source.

This produced an unresolved governance split:

  • TEMPLATE.md says “this repo is the template” (ADR-0010 language)
  • ADR-0011 says “this repo is no longer a blank template”
  • The instantiation tooling (scripts/new-repo.sh) was written for the pre-ADR-0011 placeholder model and did not cover the full system

Decision

{{PROJECT_NAME}} is simultaneously a live project and the canonical template source. These are not in conflict:

  • As a live project (ADR-0011): docs/concept.md, history/chronicle.md, and all named references to {{PROJECT_NAME}}/{{PRINCIPAL_NAME}} are real, durable documents — not placeholders. They are not replaced when someone forks the repo.
  • As a template source: the scaffolding layer — agents (.claude/agents/), Golden Rules (CLAUDE.md), archive system (archive/), HR (hr/), SOPs, and the intranet portal code (intranet/) — is the reusable payload. A new repo does not start blank; it starts as a full copy of {{PROJECT_NAME}} and replaces the {{PROJECT_NAME}}-specific content with its own.

The instantiation path is scripts/setup.sh (replacing the old scripts/new-repo.sh). It is a full-system wizard that:

  • Substitutes all hardcoded {{PROJECT_NAME}}/{{PRINCIPAL_FIRST}}/{{github-user}} identity values
  • Renames project-specific directories
  • Resets project-specific content (chronicle, reports, reviews, changelog)
  • Generates .env.example and SETUP-STATUS.md

SETUP.md (repo root) is the human-facing setup guide; it picks up where the script leaves off (GitHub, Vercel, Neon, Slack, archive re-baseline).

TEMPLATE.md is updated to reference setup.sh and this ADR.

Consequences

  • No more governance conflict: {{PROJECT_NAME}}'s identity is its own; clones replace it.
  • scripts/new-repo.sh is superseded by scripts/setup.sh (the old script is retained for reference but should not be used for new instantiations).
  • Contributors and AI agents reading TEMPLATE.md get a consistent, accurate model of how new repos are created from this one.
  • The dual-use model is explicit and recorded; future ADRs can extend it.
  • Any clone that has already been instantiated does not need to re-run setup; this ADR is a governance clarification, not a breaking change.