Skip to content

[Phase 3] Docs cutover + end-to-end new-repo validation #970

Closed

Description

@github-actions

Story

As a developer onboarding a new repo,
I want update the "Applying to a New Repository" checklists to make template + bootstrap the primary path and validate the full flow end-to-end,
so that the documented onboarding path is the one-click + one-command path, proven to produce a compliant repo.

Acceptance Criteria

  1. standards/github-settings.md and standards/ci-standards.md "Applying to a New Repository" checklists are updated to point at "Use this template" + scripts/bootstrap-new-repo.sh as the primary path, with the legacy script runbook kept only as the existing-repo fallback.
  2. An end-to-end DRY_RUN validation is recorded: Use-template (or a scratch repo) -> bootstrap-new-repo.sh (DRY_RUN) -> ring confirmation, whose intended state covers repo settings, both rulesets with bypass actors, required checks, labels, CODEOWNERS, push protection, and the recorded ring with no drift.
  3. The validated flow passes shellcheck scripts/*.sh and the lint.yml-equivalent checks with no errors.
  4. The two open onboarding questions are resolved or explicitly deferred in BOOTSTRAP.md: whether framework subtrees (frameworks/) are seeded by the template or opt-in, and whether the bootstrap performs app installs (Claude/CodeRabbit) or they remain a documented manual step.

Tasks / Subtasks

Dev Notes

  • The docs live cross-repo in petry-projects/.github: standards/github-settings.md (the 9-step settings checklist) and standards/ci-standards.md (the 13-step CI checklist). Update them via the aw-standards-sync.sh cross-repo PR pattern (STANDARDS_REPO=petry-projects/.github).
  • deploy-standard-workflows.sh remains the ongoing-sync path for EXISTING repos (out of scope to replace); the docs must state the template seeds day-0 only and ongoing updates still flow through the PR-based sync.
  • frameworks/ here are installed via git subtree (bmad-method, spec-kit, gsd); the idea-enhancer comment explicitly raised "are frameworks opt-in or seeded?" and "does bootstrap handle app installs?" — both must be answered in BOOTSTRAP.md, not left implicit.

Project Structure Notes

Primary edits are cross-repo docs in petry-projects/.github plus BOOTSTRAP.md in repo-template; the validation exercises this repo's bootstrap + apply-* scripts under DRY_RUN.

References

Likely target surface

  • scripts/aw-standards-sync.sh

Story prepared by the BMAD Scrum Master (Bob) for epic #964. Status: ready-for-dev.

Activity

  1. don-petry commented on Jun 28, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #970 — [Phase 3] Docs cutover + end-to-end new-repo validation

    Scope

    Make template + bootstrap-new-repo.sh the documented primary onboarding path, resolve the two open onboarding questions in the generated BOOTSTRAP.md, and record an end-to-end DRY_RUN validation covering the full policy surface with no drift.

    Boundary note (cross-repo)

    AC #1's checklists (standards/github-settings.md, standards/ci-standards.md) live in petry-projects/.github, not in this repo, and the dev-lead branch may not open cross-repo PRs. The cutover content + mechanism (template+bootstrap = primary path; legacy script runbook demoted to existing-repo fallback; template seeds day-0 only, ongoing updates via the PR-based sync) is captured in the recorded validation doc so it can be landed via the aw-standards-sync.sh / cross-repo PR pattern (STANDARDS_REPO=petry-projects/.github). This is flagged explicitly in the completion report.

    Implementation Checklist

    • scripts/seed-repo-template.sh — extend the generated BOOTSTRAP.md to resolve the two open questions: (a) frameworks/ subtrees are opt-in, not template-seeded; (b) app installs (Claude/CodeRabbit) remain a manual org-admin step, bootstrap only disables their check-suite auto-trigger. (AC Optimize review: small-PR and incremental fast paths #4)
    • docs/bootstrap/new-repo-validation.md — recorded end-to-end DRY_RUN walkthrough (template → bootstrap-new-repo.sh DRY_RUN → ring confirmation) + intended-state checklist (repo settings, both rulesets w/ bypass actors, required checks, labels, CODEOWNERS, push protection, recorded ring, no drift) + the AC test issue from agent #1 cross-repo cutover content. (AC test issue from agent #1, Go-live improvements for PR review agent #2)

    Tests to Write

    Test Command

    scripts/run-bats.sh tests/test_bootstrap_new_repo.bats tests/test_seed_repo_template.bats and bash .dev-lead/scripts/dev-lead-lint.sh (shellcheck + frontmatter)

  2. don-petry commented on Jun 28, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    Scope note — AC #1 is cross-repo

    The two "Applying to a New Repository" checklists live in petry-projects/.github (standards/github-settings.md, standards/ci-standards.md), not in this repo, and the dev-lead branch must not open cross-repo PRs. The cutover content + mechanism (template+bootstrap = primary path; legacy runbook demoted to existing-repo fallback; template seeds day-0 only, ongoing updates via the PR-based sync) is recorded in docs/bootstrap/new-repo-validation.md so it can be landed via the standards cross-repo PR pattern (STANDARDS_REPO=petry-projects/.github). Follow-up: open that cross-repo PR to apply the two checklist edits.

    Test Results

    # Affected files
    $ scripts/run-bats.sh tests/test_bootstrap_new_repo.bats tests/test_seed_repo_template.bats
    38 ok, 0 not ok
    
    # Full lint.yml bats suite (50 files)
    872 ok, 0 not ok
    
    # Required lint
    $ bash .dev-lead/scripts/dev-lead-lint.sh
      [lint] all checks passed   (shellcheck warning-level clean; agent frontmatter + CODEOWNERS OK)
    
    $ shellcheck --severity=warning scripts/seed-repo-template.sh scripts/bootstrap-new-repo.sh
      (clean)
    

    Files Changed

    Notes

    • TDD: the AC Optimize review: small-PR and incremental fast paths #4 assertion was written failing-first, then made green by the generator change. The new e2e test is itself the executable validation. The validation doc is pure documentation (Phase 2 exception).
    • The DRY_RUN walkthrough was captured with gh stubbed to a no-op reader, so the real apply-* sub-scripts run end-to-end without network/writes — the same seam the bats suite uses.
    • Out of scope (unchanged): deploy-standard-workflows.sh / aw-standards-sync.sh remain the ongoing-sync path for existing repos; the template seeds day-0 only.
  3. added a commit that references this issue on Jun 30, 2026
  4. added 18 commits that reference this issue on Aug 2, 2026
  5. added a commit that references this issue on Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions