rebrand-project

Files (1)

• SKILL.md

SKILL.md (first lines)

# Rebrand a project

Rename a project across every externally observable surface in one coherent breaking-version cut. The mechanical work is large (often 300–500 references) but well-bounded; the risk lives almost entirely in the **planning** phase (locking the right naming table before any edits) and the **publication** phase (the GitHub-side actions are partially irreversible).

This skill encodes the workflow that worked end-to-end in production for the Airlock → Airlock Config rename (v0.4 → v0.5). Adapt the specifics to the project at hand; the *shape* of the process is what's load-bearing.

## When this skill fires

Trigger patterns:
- "Rename the project from X to Y"
- "Rebrand the CLI / package / repo"
- "Change everything from `foo` to `bar` across the codebase"
- "I want to do a breaking version cut to rename this"
- Any time a rename touches **more than just identifiers in code** — i.e. it crosses into config keys, file extensions, URLs, HTTP headers, or a published package name.

## Workflow

### 1. Inventory pass (read-only, no edits)

Before proposing a rename plan, find every occurrence of the current name. Categorise them — different categories need different handling.

```
grep -rn -i "<oldname>" --include="*.ts" --include="*.json" --include="*.yaml" --include="*.md" .
```

Buckets to track:
- **Source code identifiers** — type names, function names, variables, CLI command, file basenames inside `src/`.
- **JSON/YAML schema + examples** — schema `$id`, `title`, top-level required properties; example files' top-level keys.
- **On-the-wire identifiers** (load-bearing — consumers depend on these):
  - File extension (`.foo.yaml`)
  - Well-known paths (`/.well-known/foo.yaml`, `/.well-known/foo/`)
  - Top-level YAML/JSON key in the contract
  - HTTP debug/response headers (`X-Foo-*`)
  - Any registered URI scheme or extension URI (`foo://`, `extensions[].uri: "foo-contract"`)
- **Tests** — assertions on all of the above.
- **Workflows + config** — `.github/workflows/*.yml` path globs, scripts directories.
- **Documentation** — README, narrative docs, ADRs.
- **URLs** — GitHub repo URL, Pages URL, schema `$id` URL, any external API references.

Report the count by category back to the user before proposing edits.

### 2. Lock a naming table

Write an explicit `old → new` table covering every surface. Show it to the user. **Do not proceed to edits until they sign off.**

| Surface | Old | New |
|---|---|---|
| Display name / brand | … | … |
| Package slug / npm `name` | … | … |
| CLI command | … | … |
| TypeScript type name | … | … |
| Schema file | … | … |
| Schema `$id` | … | … |
| Schema `title` | … | … |
| Top-level YAML/JSON key | … | … |
| File extension | … | … |
| Well-known machine path | … | … |
| Well-known portal directory | … | … |
| HTTP headers | … | … |
| A2A / extension URI | … | … |
| GitHub repo | … | … |
| Pages / live URL | … | … |
| Sister/related repos (mentioned in docs) | … | … |

If a row doesn't apply to the project, omit it — but be explicit that you considered it.

### 3. Decide the version bump strategy

- This is a **breaking** change. Bump the major (or 0.x minor, if pre-1.0).
- Write a migration doc: `docs/migration-vX-to-vY.md`. It must include a one-shot `sed` recipe consumers can run on their own contracts/files. Be specific.
- Write an ADR: `docs/adr/NNNN-rename-to-newname.md`. Use the project's existing ADR template. Cover **why** (positioning, discoverability, clarity) and the **considered options** (e.g. "keep old name + alias new one" — usually rejected because it dilutes the rename's purpose).
- **No backward-compat shim by default.** Cleanest possible cut. The migration path is the doc + a friendly validator hint (see step 5).

### 4. Order of operations (mechanical edits)

The order matters because TypeScript + tests + a validator together act as a regression net — they catch missed renames the moment you do them in the right sequence:

1. **Schema file + example files** first. Rename the file (`git mv schema/old.schema.json schema/new.schema.json`), change `$id`, `title`, and the top-level property. Rename example YAML files and update their top-level key. Tests will fail loudly, which is the point.
2. **TypeScript source** — start with the type definitions (e.g. `AirlockContract` → `AirlockConfig`). The compiler surfaces every site that imports them; update each in turn. Then rename the CLI command (`.name("airlock-config")`), well-known route paths, HTTP header strings, A2A extension URI strings, and `mkdtemp`/temp-dir prefixes.
3. **Tests** — update path constants, header assertions, extension URI assertions, top-level-key fixtures, registry field names. Re-run `npm test` (or equivalent) — must reach 100% pass.
4. **Workflows + config** — `.github/workflows/*.yml` `paths:` globs, any `scripts/` files with hard-coded URLs, `package.json` `name` / `bin` / `version` / `scripts` globs / `description`.
5. **Docs** — wholesale `README.md` rewrite (often a good moment to also refresh the aesthetic; see `refresh-readme-from-reference` skill). Then `CONTEXT.md` / glossary, narrative docs in `docs/`, the migration doc, the new ADR. **Leave historical ADRs untouched** — they describe decisions made under the old name. The new ADR cross-links them.

### 5. Friendly validator hint (if the project has a validator)

If there's a version gate or schema validator, teach it to recognise the **legacy** key/extension/URI and emit a one-line error pointing at the migration doc:

```
contract uses the v0.4 top-level key "airlock"; v0.5 renamed this to "airlock_config" and bumped the file extension to .airlock-config.yaml. See docs/migration-v04-to-v05.md for the one-shot sed recipe.
```

This is the single highest-leverage piece of polish — it converts a wall of ajv errors into one actionable message.

### 6. Local verification gate

Before *any* publication step, all of these must pass:

```sh
npm run typecheck     # surfaces missed type renames
npm test              # surfaces missed wire-name changes
npm run build         # surfaces playground/bundle issues
node dist/cli.js validate examples/<new-name>.yaml   # CLI smoke
# Then start the sandbox and curl every renamed surface:
node dist/cli.js sandbox examples/<new>.yaml --port 8080 &
curl -i http://127.0.0.1:8080/.well-known/<new-name>.yaml
curl -i http://127.0.0.1:8080/.well-known/agent-card.json    # check extension URI
curl -i -X POST http://127.0.0.1:8080/skills/...            # check new headers
node dist/cli.js check examples/<new>.yaml --url http://127.0.0.1:8080
node dist/cli.js build-site --out ./dist-pages              # check static layout
```

Treat any failure as a missed rename; fix and re-run end-to-end. Do not advance to step 7 with anything red.

### 7. Publication — confirm with the user before each step

The GitHub-side actions are **partially irreversible** (GitHub auto-redirects the old repo URL, but the canonical name has changed and the Pages URL really has moved). For each of these, state the action and pause for confirmation:

1. `git add -A && git commit -m "<rename description>"` — the local commit.
2. `gh repo rename newname --repo Owner/oldname --yes` — renames on GitHub.

From Okohedeki/dotclaude, Apache-2.0.

More from Okohedeki/dotclaude