Skip to content

Repository Template Standard

This standard defines how new repositories adopt and enforce Base Coat controls from the first commit.

Goal

  • Start every new repository from a pinned, auditable baseline.
  • Prevent silent drift from approved standards.
  • Keep upgrade paths explicit and reviewable.

Required Template Assets

Every template repository must include:

  • .github/base-coat.lock.json
  • .github/workflows/bootstrap-basecoat-template.yml
  • .github/workflows/enforce-basecoat-template.yml

The lock file is the source of truth for the approved Base Coat version.

Lock File Contract

.github/base-coat.lock.json must include:

  • baseCoatRepo: upstream repository reference.
  • version: pinned semantic tag (example: v0.3.0).
  • installPath: expected install location (default: .github/base-coat).
  • checksumRequired: boolean for release checksum policy.

Example:

{
  "baseCoatRepo": "YOUR-ORG/basecoat",
  "version": "v0.3.0",
  "installPath": ".github/base-coat",
  "checksumRequired": true
}

Bootstrap Requirements

Bootstrap workflow must:

  1. Read lock file values.
  2. Download the pinned release assets.
  3. Install into installPath.
  4. Verify required baseline directories exist.
  5. Fail if lock file and installed version diverge.

Enforcement Requirements

Enforcement workflow must run on pull requests and pushes to main.

The workflow must fail when:

  • lock file is missing or malformed,
  • baseline folders are missing,
  • installed .github/base-coat/version.json does not match locked version,
  • pull requests modify Base Coat content directly without an explicit upgrade change path.

Minimum required baseline folders in installed path:

  • instructions/
  • skills/
  • prompts/
  • agents/

Upgrade Policy

  • Upgrades are pull-request driven only.
  • Upgrade pull requests must update lock file and installed Base Coat contents together.
  • Upgrade pull requests should include release notes and risk summary.

Branch Protection Recommendations

Set these as required status checks for template consumers:

  • validate-commit-messages
  • validate-unix
  • validate-windows
  • enforce-basecoat-template

Operating Model

  • Template owner: platform or COE team.
  • Approval required from template owner for lock version changes.
  • Release cadence should be explicit (for example monthly or quarterly).

Adoption Pattern

  1. Create repository from template.
  2. Run bootstrap workflow.
  3. Commit resulting .github/base-coat content.
  4. Enable enforcement workflow as required status check.
  5. Enforce upgrades through standard pull request flow.