Repo Best Practices Bootstrap

Overview

Ensure repositories have appropriate security and best practice features configured and enabled. Applicable to both greenfield (new repository) and brownfield (existing repository) projects.

REQUIRED: superpowers:verification-before-completion

Bootstrapping Skills Decision Matrix

Use this matrix to select the appropriate bootstrapping skill:

Skill Scope Comparison

Invocation Context

• Greenfield projects: Invoke after greenfield-baseline establishes structure
• Brownfield projects: Invoke directly for security audit
• Compliance checks: Invoke directly for audit against checklist

Do NOT Use This Skill When

• Starting a brand new project without structure (use greenfield-baseline first)
• Only need quality tooling (use automated-standards-enforcement)
• Repository security already configured and passing audit

Categories covered:

1. Repository Security - Branch protection, signed commits, secret scanning, vulnerability alerts
2. CI/CD Security - Actions permissions, OIDC deployments, artifact signing, supply chain security
3. Code Quality Gates - Required reviews, status checks, linting, no direct commits
4. Documentation Baseline - README, CONTRIBUTING, LICENSE, SECURITY
5. Agent Enablement - CLAUDE.md, AGENTS.md, skills bootstrap, pre-commit hooks
6. Development Standards - .editorconfig, .gitignore, .gitattributes, pre-commit config
7. Project Management - Project board linking, kanban/sprint workflow configuration
8. Standard Tooling - husky, prettier, markdownlint, lint-staged, local secret scanning
9. Multi-Identity Workflow (Optional) - Persona-switching for role-based commits and GPG signing

When to Use

• Setting up new repository (greenfield)
• Auditing existing repository (brownfield)
• User asks to "bootstrap", "secure", or "audit" a repository
• Compliance check requested
• Onboarding a repository to this skill library

Prerequisites

• Git CLI installed and authenticated
• Platform CLI installed and authenticated:
  • GitHub: gh CLI
  • Azure DevOps: az repos CLI
  • GitLab: glab CLI
• Write access to the target repository

Platform Detection

Detect the platform from the git remote URL:

REMOTE_URL=$(git config --get remote.origin.url)

if [[ "$REMOTE_URL" =~ github\.com ]]; then
  PLATFORM="github"
  CLI_TOOL="gh"
elif [[ "$REMOTE_URL" =~ dev\.azure\.com|visualstudio\.com ]]; then
  PLATFORM="azuredevops"
  CLI_TOOL="az repos"
elif [[ "$REMOTE_URL" =~ gitlab\.com|gitlab\. ]]; then
  PLATFORM="gitlab"
  CLI_TOOL="glab"
elif [[ "$REMOTE_URL" =~ bitbucket\.org ]]; then
  PLATFORM="bitbucket"
  CLI_TOOL="manual"  # No CLI support in MVP
fi

See Platform Detection for full detection logic and CLI requirements.

Core Workflow

Step 1: Platform Detection

1. Run platform detection script
2. Verify CLI tool is installed and authenticated
3. If Bitbucket, inform user that manual configuration is required

Step 2: Load or Initialize Configuration

1. Check for .repo-bootstrap.yml in repository root
2. If file exists: Parse opt-out categories and features, skip opted-out items
3. If file does not exist (new repo):
   • Inform user: "No bootstrap configuration found. I'll guide you through setup."
   • Create .repo-bootstrap.yml with empty opt-outs
   • Proceed to guided configuration (Step 3)

Step 3: Guided Configuration

MANDATORY: Walk through ALL 8 categories. Categories cannot be skipped. Only individual features within a category can be opted out.

For each category, interactively guide the user through configuration:

1. Present the category and explain its purpose
2. Check current state using platform CLI
3. For each unconfigured feature:
   • Explain what it does and why it matters
   • Ask user: "Would you like to configure this? (Yes/No/Skip)"
   • If Yes: Proceed with configuration (Step 4)
   • If No/Skip: Record opt-out with reason (Step 3a)
4. For paid features without free tier:
   • Present free/open-source alternatives (see Cost Considerations)
   • Offer to configure the alternative instead

See Checklist for the complete checklist with platform-specific commands.

Step 3a: Record Opt-Out Decision

When a user declines a feature:

1. Ask for reason: "Why are you skipping this? (brief explanation)"

2. Record in .repo-bootstrap.yml:

   opt_out:
     features:
       - feature-name # Reason: user explanation

3. Create ADR if significant: For security-related opt-outs, create an Architecture Decision Record in docs/decisions/:

   # ADR-NNN: Skip [Feature Name]
   
   ## Status
   
   Accepted
   
   ## Context
   
   [Why this decision was made]
   
   ## Decision
   
   We will not implement [feature] because [reason].
   
   ## Consequences
   
   [What this means for the project]

Step 4: Configure Features

For each feature the user wants to configure:

1. Guide through options: Present configuration choices with recommendations
2. Use platform CLI to enable/configure the feature
3. Create files from templates and prompt user to customize:
   • CODEOWNERS: "Who should be listed as code owners?"
   • Branch protection: "What status checks should be required?"
   • Dependabot: "Which package ecosystems do you use?"
4. Commit changes with descriptive message referencing the feature

See templates in templates/ directory for documentation and configuration files.

Signed Commits (Special Handling)

WARNING: Do NOT enable signed commits in branch protection until setup is verified.

When user selects "Yes" to signed commits, guide them through setup interactively:

Step A: Check current GPG setup

# Check if GPG is installed
gpg --version

# Check for existing keys
gpg --list-secret-keys --keyid-format=long

Step B: Guide through setup if needed

Ask: "Do you have a GPG key configured for signing commits?"

• If No: Guide through playbook steps:
  1. Generate key: gpg --full-generate-key (RSA 4096, matching email)
  2. Get key ID: gpg --list-secret-keys --keyid-format=long
  3. Export public key: gpg --armor --export KEY_ID
  4. Add to platform (GitHub Settings > SSH and GPG keys)

  5. Configure git:

     git config --global user.signingkey KEY_ID
     git config --global commit.gpgsign true

• If Yes: Verify configuration:

  git config --get user.signingkey
  git config --get commit.gpgsign

Step C: Add git hook verification

Add blocking check to .husky/pre-commit:

# Require GPG commit signing to be configured
if [ "$(git config --get commit.gpgsign)" != "true" ]; then
  echo ""
  echo "❌ ERROR: GPG commit signing is not enabled"
  echo "   All commits must be cryptographically signed."
  echo ""
  echo "   To enable signed commits:"
  echo "   1. Follow the setup guide: docs/playbooks/enable-signed-commits.md"
  echo "   2. Configure git: git config --global commit.gpgsign true"
  echo "   3. Ensure your GPG key is added to GitHub"
  echo ""
  echo "ℹ️  To bypass (not recommended): git commit --no-verify"
  exit 1
fi

Create .husky/pre-push to detect commits with invalid or missing signatures:

# Check for unsigned or invalid commits before pushing
# Valid signatures: G (Good), U (Good but untrusted)
# Invalid: N (None), B (Bad), E (Error), R (Revoked), X/Y (Expired)

REMOTE="$1"
URL="$2"

# Detect the default branch dynamically
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$DEFAULT_BRANCH" ]; then
  DEFAULT_BRANCH="main"
fi

while read local_ref local_sha remote_ref remote_sha; do
  # Skip branch deletions and tag pushes
  if [ "$local_sha" = "0000000000000000000000000000000000000000" ]; then
    continue
  fi
  if echo "$local_ref" | grep -q '^refs/tags/'; then
    continue
  fi

  if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
    # New branch - check commits since divergence from default branch
    merge_base=$(git merge-base "origin/$DEFAULT_BRANCH" "$local_sha" 2>/dev/null)
    if [ -n "$merge_base" ]; then
      range="$merge_base..$local_sha"
    else
      range="$local_sha~50..$local_sha"
    fi
  else
    range="$remote_sha..$local_sha"
  fi

  # Check for any non-valid signatures
  invalid=$(git log --format="%H %G?" "$range" 2>/dev/null | grep -vE " [GU]$" | cut -d' ' -f1)

  if [ -n "$invalid" ]; then
    echo ""
    echo "❌ ERROR: Found commits with invalid or missing signatures"
    echo ""
    echo "To fix, rebase and re-sign your commits:"
    echo ""
    echo "  git rebase origin/$DEFAULT_BRANCH --exec 'git commit --amend --no-edit -S'"
    echo "  git push --force-with-lease"
    echo ""
    echo "See: docs/playbooks/enable-signed-commits.md"
    echo ""
    echo "ℹ️  To bypass (not recommended): git push --no-verify"
    exit 1
  fi
done

exit 0

Step D: Test before enabling branch protection

# Create test commit
git commit --allow-empty -m "test: verify GPG signing"

# Verify signature
git log --show-signature -1

Step E: Enable branch protection only after test passes

# GitHub
gh api repos/OWNER/REPO/branches/main/protection/required_signatures -X POST

Generate docs/playbooks/enable-signed-commits.md from template for future reference.

See Signed Commits Playbook Template.

Step 4a: Persona-Switching Integration (Optional)

After core configuration, offer multi-identity workflow setup:

Detection

Check if persona-switching is already configured:

# Check for existing playbook
if [ -f "docs/playbooks/persona-switching.md" ]; then
  echo "Persona-switching already configured - skipping"
  # Report as "already configured" in summary
else
  # Proceed to prompt
fi

Prompt

Ask user: "Enable multi-identity workflow?" (Y/n)

• Default: No (persona-switching is optional)
• If Yes: Chain to persona-switching skill setup flow
• If No: Record opt-out and continue

If Enabled

Chain to persona-switching skill setup flow:

1. Role Discovery - Parse existing docs/roles/*.md or use defaults
2. Security Profile Configuration - Map personas to GitHub accounts
3. Generate Artifacts:
   • docs/playbooks/persona-switching.md - Repository playbook
   • ~/.config/<repo-name>/persona-config.sh - User's shell config
4. Verify Setup - Test use_persona and show_persona commands

See persona-switching skill for full setup flow.

If Declined

Record opt-out in .repo-bootstrap.yml:

opt_out:
  features:
    - persona-switching # optional - user declined

No justification required (optional feature).

Continue Bootstrap

After persona-switching setup completes (or is declined), continue with Step 5.

Step 5: Generate CI/CD Workflow

IMPORTANT: Pre-commit hooks can be bypassed. CI/CD enforcement is mandatory.

1. Mirror pre-commit rules in CI/CD:
   • If lint-staged configured → Add linting job to CI
   • If prettier configured → Add format check to CI
   • If secretlint configured → Add secret scanning to CI
2. Generate workflow file from template (.github/workflows/ci.yml)
3. Configure branch protection to require CI checks pass before merge
4. Verify enforcement: Ensure same rules apply locally and in CI

See CI/CD Templates for workflow templates.

Step 6: Verify Configuration

1. Re-run checklist to verify all selected items are now compliant
2. Document any items that could not be configured automatically
3. Run CI workflow to verify it passes
4. Report final compliance status

Opt-Out Mechanism

Users can opt out of specific features within a category. Opt-outs are respected during checklist execution and do not generate gaps.

IMPORTANT: Categories cannot be skipped. All 8 categories must be presented to the user. Only individual features can be opted out.

Feature opt-out: Skip a specific feature (with documented reason)

When a feature is opted out, document the reason via ADR (preferred) or opt-out file.

Opt-Out Persistence

Preferred: Use ADRs in docs/decisions/ to document opt-out decisions with full context.

Alternative: If ADRs are not used, store opt-outs in .repo-bootstrap.yml:

# .repo-bootstrap.yml
# Repository bootstrap configuration
# See: skills/repo-best-practices-bootstrap/SKILL.md

opt_out:
  features:
    - signed-commits # Reason: team not using GPG keys
    - artifact-signing # Reason: not publishing artifacts

Commit the opt-out documentation to persist decisions across sessions.

Cost Considerations

Some features require paid plans. The checklist indicates cost for each feature.

See Cost Considerations for:

• Features requiring paid plans
• Free alternatives for each paid feature
• Platform-specific pricing notes

See Also

• Checklist - Complete checklist with platform-specific commands
• Platform Detection - Detection logic and CLI requirements
• Cost Considerations - Paid features and free alternatives
• skills-first-workflow AGENTS Template - Template for AGENTS.md file

Minimum Viable Bootstrap Profile

The minimum viable set of practices to bootstrap a repository.

See Minimum Viable Bootstrap Profile.

Automated Feature Checks

Automated checks that detect which practices/features are already present.

See Automated Feature Checks.

Red Flags - STOP

These statements indicate bootstrap anti-patterns: