Create a GitHub template repository to scaffold new petry-projects repos with org standards

[don-petry]

Summary

Create a GitHub template repository (petry-projects/repo-template) that scaffolds new org repos
with our standards already in place, so spinning up a compliant repo is one "Use this template" click
plus a single bootstrap step — instead of the current manual copy-from-standards/ runbook. Today a new
repo only becomes compliant after someone hand-copies caller stubs, config, and docs, then runs the
settings/ruleset scripts. A template repo turns the file scaffold half of that into a button; an
explicit bootstrap must turn the org-policy / settings half into one command — including
confirming which release ring the new repo joins.

Background — verified gaps

Researched across petry-projects/.github (standards source), .github-private, and the 6 product
consumers (ContentTwin, TalkTerm, bmad-bgreat-suite, broodly, google-app-scripts, markets):

• No template repository exists. gh repo list shows none flagged is_template. Onboarding is
  entirely script + PR driven: scripts/deploy-standard-workflows.sh, apply-repo-settings.sh,
  apply-rulesets.sh, plus the manual "Applying to a New Repository" checklists in
  standards/github-settings.md (9 steps) and standards/ci-standards.md (13 steps).
• There is a stable, well-defined common baseline every consumer carries — this is exactly what a
  template should ship:
  • .github/workflows/ thin caller stubs (≈10): agent-shield.yml, auto-rebase.yml, ci.yml,
    copilot-setup-steps.yml, dependabot-automerge.yml, dependabot-rebase.yml,
    dependency-audit.yml, dev-lead.yml, pr-review-mention.yml, sonarcloud.yml
    (+ optionally feature-ideation.yml). All present in all 6 consumers.
  • .github/CODEOWNERS (* @petry-projects/org-leads), .github/dependabot.yml — all 6.
  • Root: AGENTS.md, CLAUDE.md (1-line pointer to org AGENTS.md), sonar-project.properties,
    .gitignore, LICENSE — all 6; SECURITY.md, README.md, .coderabbit.yaml — 5/6.
• The canonical content already lives in standards/ (workflow stubs in standards/workflows/,
  per-stack Dependabot in standards/dependabot/, gitleaks.toml, etc.). A template repo is a
  packaging/distribution layer over content we already maintain — not new policy.

The key constraint (shapes the whole design)

Per GitHub docs, a template repository copies only files + (optionally) branches — with unrelated
history. It does NOT carry repository settings, branch protection, rulesets (pr-quality,
code-quality), required status checks, labels, secrets, Dependabot/GHAS security config, or
collaborators. Those are precisely the non-file standards our apply-repo-settings.sh /
apply-rulesets.sh / security-config scripts apply today.

Implication: the template solves the file scaffold only. Full compliance still needs the
settings/ruleset/security step. The clean design is therefore template repo + a one-shot bootstrap
(a workflow_dispatch "repo-init" workflow, or a documented scripts/init-new-repo.sh wrapper) that,
after creation, invokes the existing apply-* scripts against the new repo. The template gets you the
files in one click; the bootstrap closes the rest.

Bootstrap: org policies & settings (the non-file half — must be explicit)

The bootstrap must apply the full non-file standard surface by reusing the existing scripts (no
reimplementation). Concretely it must cover:

• Repo settings (apply-repo-settings.sh): squash-only merge (disable merge/rebase), auto-merge,
  delete-branch-on-merge, and the standard general settings.
• Security & analysis (apply-repo-settings.sh + push-protection lib): GHAS / security_and_analysis
  per standards/advanced-security.md, secret-scanning push protection + custom patterns per
  standards/push-protection.md, Dependabot security updates.
• Rulesets (apply-rulesets.sh + fix-ruleset-bypass.sh): the two sanctioned rulesets only —
  pr-quality (1 approval, code-owner review, required thread resolution, dismiss-stale, squash-only)
  and code-quality (required status checks, strict: true, enforce-for-admins) — each with the
  mandatory bypass actors dependabot-automerge-petry (App) + OrganizationAdmin, both
  bypass_mode: always. Legacy/ad-hoc main rulesets must not be created.
• Required status checks: wired to the repo's actual check names (CodeQL context, SonarCloud,
  Dev-Lead Agent / dev-lead, CI pipeline name, coverage, Secret scan (gitleaks),
  dependency-audit / Detect ecosystems — not the per-ecosystem jobs, which skip).
• Standard label set + CODEOWNERS team (@petry-projects/org-leads first owner).
• Check-suite auto-trigger prefs (fix-check-suite-prefs.sh) and add-to-project board wiring.

This makes "org repo policies and settings" a first-class, automated bootstrap output rather than an
implied follow-up.

Release-ring assignment (confirm at setup — currently silent)

Ring membership is not encoded in a repo's own stubs. It lives centrally in two files that must stay
in sync, both read by the compliance audit and the deploy sweep:
standards/canary-rings.json (.github-private) and scripts/lib/ring-pins.sh (.github). The model is
next → ring0 → ring1 → stable.

• Default today is silent stable via the * catch-all (*) printf 'stable') — a new repo joins the
  broad fleet with no decision point and its stubs pin @<agent>/stable.
• To make a new repo an early canary (e.g. ring1, like TalkTerm / bmad-bgreat-suite) you must
  edit both central files and pin its stubs to the matching ring channel — otherwise audit/deploy
  flag drift.

The bootstrap must therefore prompt/confirm the repo's ring (default stable) and, when a non-stable
ring is chosen, register the repo in canary-rings.json and ring-pins.sh (keeping them in sync) and
pin the shipped stubs to that channel. Even when the answer is stable, recording the confirmation makes
ring membership a deliberate, auditable choice instead of an accident of the wildcard.

Goals

• Cut "new repo → compliant repo" from a multi-step manual checklist to: click Use this template →
  run one bootstrap command/workflow that applies files and org policies/settings and confirms
  the release ring.
• Single source of truth: the template's stubs/config stay verbatim copies of standards/ (CI must
  guard drift), so the template never becomes a competing fork of the standards.
• Pin published channel tags (@<name>/stable by default, public @v2, private @main) in shipped
  stubs — not the local dogfood ./... refs the source repos use internally.
• Make the non-file gap (settings, rulesets, security, ring) explicit and automated, not a footgun.

Acceptance criteria

• A petry-projects/repo-template repo exists, flagged as a template repository.
• It contains the baseline file scaffold above, with workflow stubs copied verbatim from
  standards/workflows/ and Dependabot from the appropriate standards/dependabot/ stack template.
• Workflow stubs pin published channel tags, not local ./... refs.
• CLAUDE.md is the 1-line pointer; AGENTS.md follows the consumer convention.
• A documented bootstrap (workflow_dispatch and/or scripts/init-new-repo.sh) applies the full
  non-file policy surface above — repo settings, security/GHAS + push protection, the
  pr-quality + code-quality rulesets with the required bypass actors, required status checks,
  labels, CODEOWNERS, check-suite prefs — by reusing the existing apply-* scripts (no reimplementation).
• The bootstrap confirms the release ring (default stable); for a non-stable ring it registers
  the repo in both standards/canary-rings.json and scripts/lib/ring-pins.sh and pins stubs to
  the matching channel. The chosen ring is recorded/auditable even when it is stable.
• Drift guard: a CI check (here or in .github) fails if the template's stubs/config diverge from
  standards/, so the template stays a thin distribution layer.
• The "Applying to a New Repository" checklists in github-settings.md / ci-standards.md are
  updated to point at the template + bootstrap as the primary path.
• Multi-stack handled: either per-stack template variants (frontend / backend-python / backend-go /
  fullstack) or a documented post-clone "pick your Dependabot + ci.yml" step (ci.yml is the one
  stub with real build/test steps and must be customized per stack).

Out of scope

• Migrating existing repos (this is for new repos; existing ones keep using the sync scripts).
• Replacing deploy-standard-workflows.sh ongoing sync — the template seeds day-0; ongoing updates to
  already-created repos still flow through the existing PR-based sync.
• Any new policy/standard — this only repackages existing standards for faster onboarding.
• Issue/PR templates and a labeler config (none exist anywhere today; don't introduce as a side effect).

Assessment

Dimension	Score	Rationale
Feasibility	high	All content already exists in standards/; apply-* scripts and the ring config already exist. Mostly packaging + a bootstrap wrapper + a drift-guard check.
Impact	medium	Removes recurring onboarding friction and a class of "new repo missed a standard / silently defaulted ring" gaps; low blast radius (new repos only).
Urgency	low–medium	No active incident, but new repos appear periodically and each is manual today.

Adversarial review

Strongest objection: "A template repo duplicates standards/ and will drift — we'd maintain the
same stubs in two places." Rebuttal: valid, and it's why the drift-guard CI check + verbatim-copy
rule are acceptance criteria. The template must be a distribution artifact of standards/, regenerable
from it, not a hand-edited fork. If a drift guard proves too costly, the fallback is generating the
template contents from standards/ in CI rather than committing them.

Suggested next step

Have the initiative-planner scope this as: (1) template repo + verbatim scaffold, (2) bootstrap
workflow/script wrapping the apply-* scripts for the full policy/settings surface, (3) release-ring
confirmation + central-config registration, (4) drift-guard CI, (5) docs update — and decide
single-template-with-post-clone-choices vs. per-stack variants for the Dependabot/ci.yml split.

[github-actions[bot]]

Sharpened problem & goal

Create petry-projects/repo-template so spinning up a compliant new org repo goes from a multi-step copy-from-runbook to "Use this template" + a single bootstrap command. The key ambiguity worth clarifying before scoping: which compliance items live in template files (caller stubs, CLAUDE.md, AGENTS.md) vs. which must be applied post-creation via API? The latter class — check-suite auto-trigger preferences, rulesets, branch protection — cannot be seeded by a template click alone; it needs an explicit bootstrap step that runs against the newly created repo.

Context

Two scripts in this repo already cover the post-creation half and are designed for exactly this use:

• scripts/apply-repo-settings.sh — idempotently enforces org-standard check-suite auto-trigger settings (disabling the Claude and CodeRabbit app IDs that permanently block auto-merge) and push-protection settings. Supports --all or a single owner/repo target.
• scripts/apply-rulesets.sh — idempotently applies all rulesets in .github/rulesets/*.json to a target repo (create-or-update). Already DRY_RUN-safe.

A scripts/bootstrap-new-repo.sh wrapper that chains these two against a fresh repo would close the compliance gap with a single command. Agent profiles in agents/ are org-wide (they live here and are inherited automatically) — no per-repo copy needed. Workflow caller stubs are the main file-level deliverable for the template.

Impact / Effort

Impact	HIGH — each new repo today carries a manual, error-prone runbook; compliance is frequently deferred, producing repos that hit CI failures or block auto-merge on day one
Effort	M — template repo creation is low; the real work is the bootstrap wrapper + a tested end-to-end new-repo flow

Suggested acceptance criteria

• petry-projects/repo-template is a GitHub template repository containing at minimum: caller stubs for thin-caller workflows (auto-rebase.yml, agent-shield.yml, dependabot-automerge.yml), a starter CLAUDE.md that references AGENTS.md, and a BOOTSTRAP.md quick-start guide.
• scripts/bootstrap-new-repo.sh owner/new-repo (DRY_RUN-aware) invokes apply-repo-settings.sh + apply-rulesets.sh in sequence, exits non-zero if either fails, and prints a clear pass/fail summary.
• Applying the template + running bootstrap produces a repo that passes shellcheck scripts/*.sh and lint.yml-equivalent checks with no errors.
• Clarify and document: are framework subtrees (frameworks/) opt-in or seeded by the template?
• Clarify: does the bootstrap step handle app installs (e.g., Claude, CodeRabbit), or does that remain a manual step documented in the quick-start?

[github-actions[bot]]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #964 — Initiative: GitHub template repo + bootstrap for one-click compliant new petry-projects repos

6 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Create petry-projects/repo-template as a flagged template repository #965 (S) — [Phase 1] Create petry-projects/repo-template as a flagged template repository
• [Phase 1] Seed the verbatim file scaffold into repo-template #966 (M) — [Phase 1] Seed the verbatim file scaffold into repo-template
• [Phase 2] Bootstrap wrapper: scripts/bootstrap-new-repo.sh applies the full non-file policy surface #967 (M) — [Phase 2] Bootstrap wrapper: scripts/bootstrap-new-repo.sh applies the full non-file policy surface
• [Phase 2] Release-ring confirmation + central-config registration in the bootstrap #968 (M) — [Phase 2] Release-ring confirmation + central-config registration in the bootstrap
• [Phase 1] Drift-guard CI: fail when template stubs diverge from standards/ #969 (M) — [Phase 1] Drift-guard CI: fail when template stubs diverge from standards/
• [Phase 3] Docs cutover + end-to-end new-repo validation #970 (M) — [Phase 3] Docs cutover + end-to-end new-repo validation

Open questions for review:

• Single-template-with-post-clone-choices vs per-stack template variants (frontend / backend-python / backend-go / fullstack) for the Dependabot + ci.yml split: Story 2 implements the single-template + documented post-clone default (sanctioned by the idea's AC); confirm before investing in per-stack variants.
• Canonical home of the pr-quality ruleset JSON: codify it in this repo's .github/rulesets/ alongside code-quality.json, or in petry-projects/.github so apply-rulesets.sh reads it from there? Affects how the bootstrap (Story 3) applies both sanctioned rulesets.
• repo-template visibility (private vs public) and where the drift-guard CI should live (in repo-template, petry-projects/.github, or .github-private)?
• Do framework subtrees (frameworks/) get seeded by the template or stay opt-in, and does the bootstrap perform app installs (Claude / CodeRabbit) or are they a documented manual step? (Surfaced by the idea-enhancer comment; resolved in Story 6.)

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #964 to hand it to initiative-driver for auto-implementation.

[don-petry]

Delivered complete