Naming a New Repo

The Test

Read the repo name out loud. If a smart person who has never seen this codebase cannot guess what it does within five seconds, the name is wrong.

The corollary, which is the real reason this SOP exists: a year from now, scrolling my own GitHub list, I should not have to open a repo to remember what it does. Every time I have, the name was the problem.

The Standard

1. Lowercase, hyphenated. gmail-helper, not GmailHelper or gmail_helper. URLs, paths, and filenames all want this format anyway.
2. Subject + what it does. The name has two halves — the thing it acts on (subject) and the action or role (verb or noun). desktop-organizer, fb-spam-remover, whois-lead-scraper, update-manager. Both halves are required.
3. No bare two- or three-letter abbreviations. cc, tms, gkp, ath, mts mean nothing on their own. If an abbreviation is part of the subject, it must be paired with a descriptive second half: tms-internal, gkp-website, ath-upload-receiver. Never cc standing alone.
4. Spell out the platform when it matters. fb-, youtube-, gmail-, linkedin- are fine prefixes because they are universally understood. ghl- is fine in my world but should always pair with a descriptive second half.
5. Avoid jokes and inside references. I will lose the joke before I lose the repo. fb-email-slurper-3000 was cute in the moment and I now wince at it. Future me would prefer fb-group-member-scraper.
6. Avoid version numbers and dates in the name. v2, 2026, new, final all rot. If the repo is genuinely the second version, the name is the same and the old one gets renamed with -old (voice-first-old).
7. Length cap is loose, not tight. Three or four words is fine. claude-code-second-brain-cohort is long but it is also unambiguous, which is the whole point.

The Five-Second Test, in Practice

Pass:

• gmail-helper — Gmail intelligence layer.
• fb-spam-remover — auto-declines spam in FB groups.
• desktop-organizer — sorts my desktop.
• whois-lead-scraper — scrapes WHOIS for leads.
• update-manager — manages updates across machines.
• youtube-clipseeker — finds clips inside my YouTube library.
• cloudflare-audit — audits my Cloudflare zones.
• fb-messenger-voice-transcriber — long, but every word earns its place.

Fail:

• cc — Two letters. Means “Claude Code” in my head only. Should be claude-code-config or claude-code-kernel.
• tms-ops — tms is opaque without context, and ops is too vague. Better: marketing-show-episode-pipeline.
• pullall — One word, no hyphen, action-only. Better: repo-puller or apps-folder-syncer.
• dispatch — Vague. Could be email, logistics, anything. Better: agent-inbox-router.
• auditor — Vague. Better: infrastructure-auditor.
• loose-ends — Cute, but does not describe what it does. Better: unfinished-thread-harvester.
• the-one-thing — Three articles, no payload. Better: daily-priority-tracker.
• first-pass — Could mean anything. Better: video-first-pass-editor.
• dispatch, standup, pullall, auditor — all single-word, all need a second half.

The bad examples above are mine, currently in use, and on the rename queue.

Privacy Default

Always create as private:

gh repo create [name] --private

Public is the exception. If a repo will ever be public (a tool I want to share, a published example), make it public deliberately, not by accident.

Companion Setup

Every new repo gets the same starter kit so future me does not have to remember what was missing:

1. build.txt with starting value 1:

   echo 1 > build.txt

2. CLAUDE.md copied from the template:

   cp ~/apps/cc/templates/CLAUDE.md ./CLAUDE.md

   Fill in the placeholders. This file is what every Claude session reads when working in the repo.
3. Decide where this repo lives — fill in the Sync: header in CLAUDE.md. Per Repo Sync Policy, every repo declares its machine allocation as a single line at the top of CLAUDE.md. Default for a new repo is studio, mbp. Add vps if it runs a service there, remote-mac if it drives Chrome unattended, or use all for foundational shared tooling. Always enumerate machines explicitly — no desk or vps-only shorthand. Claude must ask this at creation time: “Where does this live? Studio and MBP only, or also VPS or Remote Mac?” Do not skip past it.
4. .gitignore appropriate for the language/framework.
5. README.md — one paragraph. What it is, where it is headed. Mirrors the entry in Repos.
6. vision.md — the durable reasoning. What problem the repo solves, what it IS, what it is NOT, the phases, the non-negotiables. Longer than README.md but shorter than a wiki page. See ~/apps/chief-of-staff/vision.md as the reference. Future me (and future Claude sessions) read this when they need to decide whether a proposed change fits the repo’s purpose.
7. First commit:

   git add -A && git commit -m "Build 1: initial commit"
   git push

8. Add it to Repos with a one-paragraph entry: what it is, where it is headed.

If the repo will deploy to Cloudflare Pages, follow Cloudflare Pages — Deploy via GitHub Actions Only before the first push.

Renaming an Existing Repo

If a repo is on the rename queue (see the Fail list above), the rename is cheap:

gh repo rename [new-name]
git remote set-url origin git@github.com:ojhurst/[new-name].git
mv ~/apps/[old-name] ~/apps/[new-name]

Then update:

• Entity aliases: ~/apps/cc/entity-aliases.json (and re-run python3 ~/apps/cc/sync-entity-aliases.py)
• Repo registry: ~/apps/cc/repo-registry.md (auto-regenerated on next pullall)
• Any cron jobs, systemd services, or launchd plists that reference the old path
• Any other repo that pulls from this one as a dependency

The cost of a bad name compounds every time you scan the GitHub list. The cost of renaming is one afternoon, once.

Related

• Repos — the portfolio view of every repo
• Cloudflare Pages — Deploy via GitHub Actions Only — for any repo that ships a website
• Adding a Page to tms-internal — how to document a new repo on this wiki