Organizing my GitHub: conventions for a personal portfolio

You spin up a repo to test an idea, name it whatever, and move on. Do that across a few years and your profile reads like a junk drawer. I cleaned mine up. Below is the system I landed on.

The mess

Names like test2 and final-version, half the repos with no README, a few private projects that should have been public and one public repo that should have been private. A recruiter who lands on that profile learns one thing: I don't tidy up.

Goals

Three, in order:

1. A stranger can tell what each repo is from the name alone.
2. The public set tells a coherent story; the private set holds the rest without leaking.
3. The convention is cheap enough that I'll follow it on the next repo, not abandon it.

Convention: <scope>-<what>

Every repo name is a scope, a hyphen, and a short description of the thing. app-vienos-dashboard. upscale-amd-vulkan. The scope says what kind of project it is; the rest says what it does. No version numbers, no dates, no -final.

Scope registry

The scopes are a small, closed set so they stay meaningful: app for runnable applications, tool for single-purpose CLIs and scripts, web for sites, skill for reusable AI/automation pieces, study for learning projects I'm not pretending are production. Keep the list closed. Allow a new scope per repo and the scope stops carrying any information.

Forbidden suffixes

-final, -v2, -new, -test, -copy. Git already tracks versions; the name shouldn't. If a rewrite is a different project, it gets a different what, not a suffix.

README pattern

Every public repo gets the same opening: one sentence on what it is, a short "why it exists," how to run it, and the stack. The first sentence shows up in search results and link previews, so I make it state the thing plainly. No warming up.

Archive vs delete

Default to archive, not delete. Archiving keeps the history readable and the link alive while signaling "not maintained." I delete only when a repo has zero value to anyone, including future me.

AI guidance leakage

Instruction files (CLAUDE.md and similar) and local config carry personal notes, paths, or workflow details you didn't mean to publish. I follow two rules now. Those files stay git-ignored in public repos. And deleting a file in a later commit does not remove it from history. If something sensitive ever landed in a public repo, you rewrite history or recreate the repo clean. There is no softer fix.

What I'd do differently

I'd have set the convention on day one instead of retrofitting it across years of repos. Renaming is cheap; un-confusing a recruiter who already bounced is not. If you're starting now, write the scope registry first and name the very next repo by it.