Repo Bootstrap

Repo Bootstrap

Getting the substrate right once removes a hundred small frictions later. This skill covers the baseline files, the ordering, and the pre-publication scrub that catches what you cannot un-publish.

Order of operations

Do these in order. Each unlocks the next.

1. Name and one-liner — you cannot write a README without them
2. License — before the first external contribution, not after (license-and-legal)
3. .gitignore + .editorconfig — before the first commit that leaks build artifacts
4. README skeleton — install → usage → why (readme-that-converts)
5. CI — a green check on the first PR sets the standard (ci-pipelines)
6. CONTRIBUTING + CODE_OF_CONDUCT — before you invite anyone
7. Issue/PR templates — before the issue tracker gets noisy (issue-triage)
8. SECURITY.md — before someone needs to report a vulnerability (supply-chain-security)
9. First tagged release — an untagged repo reads as unfinished (release-engineering)

The baseline file set

Templates for each live in assets/ next to this skill. Read them with the Read tool and adapt — never paste a template with {{PLACEHOLDER}} left in.

Repository layout

Language communities have strong conventions; follow them over any generic advice.

.
├── src/ or lib/ or <pkgname>/   # the actual code, one obvious root
├── tests/                       # mirrors src/ structure
├── docs/                        # anything longer than the README
├── examples/                    # runnable, CI-tested, no pseudo-code
├── scripts/                     # dev tooling, not shipped
└── .github/                     # workflows, templates, CODEOWNERS

Rules that hold across languages:

• One obvious entry point. A newcomer should find "where does execution start" in under 30 seconds.
• examples/ must run. Broken examples are worse than no examples — they signal the whole project is stale. Wire them into CI.
• No misc/, stuff/, new/, old/, temp/, v2/. These are unmerged decisions.
• Tests mirror source paths. src/auth/token.ts → tests/auth/token.test.ts.

Pre-publication scrub

Run before the repo goes public. This is the irreversible step — Git history is public forever, and GitHub caches deleted forks and dangling commits.

# Secrets across ALL history, not just HEAD
pip install detect-secrets 2>/dev/null; detect-secrets scan --all-files
gitleaks detect --source . --redact        # if available

# Manual sweep of high-signal patterns
git log -p --all | grep -nEi 'api[_-]?key|secret|password|BEGIN [A-Z ]*PRIVATE KEY|xox[baprs]-|ghp_|AKIA[0-9A-Z]{16}'

# Internal references that shouldn't ship
grep -rniE 'internal\.|\.corp|jira\.|confluence|@yourcompany\.com|TODO\(.*@' \
  --exclude-dir=.git . | head -40

# Large files that bloat every clone forever
git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | awk '$1=="blob" && $3>1000000 {print $3, $4}' | sort -rn | head -20

Non-negotiables:

• A leaked credential in history is leaked. Rotate it. Rewriting history with git filter-repo or BFG is cleanup, not remediation — assume it was scraped.
• Decide history strategy before publishing. Keeping internal history is honest and preserves attribution; squashing to one commit is safer if the history contains employer-internal discussion. Squashing after publication is pointless.
• Check employer IP policy before open-sourcing work code. This is a real legal question and you should tell the user to get a real answer, not guess for them.

Naming and positioning

The name is the most-repeated string in the project's life. Test it:

• Pronounceable in one try, over a video call, by a non-native speaker
• Searchable — not a common English word; "search <name> github" should find you
• Available — GitHub org/repo, package registry (npm/PyPI/crates), domain, and the social handle you will eventually want
• Not trademarked in your space, and not <BigCorpProduct>JS

The one-liner matters more than the name. Under 12 words, no adjectives, states the category and the differentiator:

• Bad: "A modern, blazing-fast, developer-friendly toolkit for the next generation of apps"
• Good: "A build tool for JavaScript that skips bundling in development"

If you cannot write that sentence, the project scope is not settled yet. Fix that before writing any docs.

Anti-patterns

• Publishing without a license. Legally, "no license" means nobody may use it. This is the single most common fatal mistake.
• README.md containing only the project name. Ship even three sentences.
• Copying a CoC without setting the contact address. [INSERT EMAIL] in a live repo signals the whole thing is decoration.
• Committing secrets, then deleting them in a follow-up commit. They stay in history.
• Ten templates before one user. Baseline files, then real work, then process.