diff --git a/CHANGELOG.md b/CHANGELOG.md index ef03e46..4cf8f80 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 — the standard prescribes not pre-creating empty directories — while the marker covers only the token it follows, so an unmarked broken path in the same row still fails. Documented in the standard's *Variance declarations* (*Planned paths*) and covered by two smoke cases. +- Two `/new-repo` documentation gaps observed in a scaffolding session (#33): the skill now + documents **adopting a directory that already has content** (inventory first, pre-existing + content wins collisions, two commits with the import before the scaffold, recorded in + ADR-0001), and the naming conventions state that a deliberate **branding name** is an + allowed exception to the kebab-case default — the user's own product name is accepted and + recorded in ADR-0001, not argued with. ## [0.6.0] - 2026-08-13 diff --git a/plugins/repokit/skills/new-repo/SKILL.md b/plugins/repokit/skills/new-repo/SKILL.md index 34fd8fd..afb1e37 100644 --- a/plugins/repokit/skills/new-repo/SKILL.md +++ b/plugins/repokit/skills/new-repo/SKILL.md @@ -24,7 +24,9 @@ Two reference files (read them from the same base dir as you need them): Gather these from the user's arguments / message, else ask — keep it to load-bearing questions: -- **name** — the repo / directory name (kebab-case). +- **name** — the repo / directory name. Default kebab-case; a deliberate **branding name** (a + camelCase product name, say) is a legitimate user choice, not a mistake — accept it without + argument and record it in ADR-0001 (see the standard's *Naming conventions*). - **description** — one line. - **type** — one of: `powershell-module`, `docker-compose`, `power-platform-connectors`, `skill-plugin`, `collection`, `mcp-server`, `app-ts`, `app-python`, `script-collection`. @@ -45,6 +47,27 @@ If the chosen type is a **stub** (anything other than `powershell-module`, `dock Core/Public/Published files get stamped, but there's no type-specific structure yet. Confirm they want to continue. +## Adopting a directory that already has content + +The target directory may already contain files (a design doc written before repo genesis, a +prototype script). That is supported — scaffold *around* the content instead of improvising: + +1. **Inventory first.** List the existing files. If the directory is already a git repo + (`.git/` present), stop — that is a retrofit, not a scaffold: apply the standard by hand + and add the adoption marker (see the standard, *Variance declarations*). +2. **Collision rule: pre-existing content wins.** Intersect the resolved file set (step 1 + below) with what is on disk. Never overwrite a pre-existing file with a template — skip + each colliding template, list the collisions in the final summary, and leave merging + template content into the user's file (say, folding the README boilerplate into their + existing README) as a follow-up the user approves. +3. **Two commits, pre-existing first** — this replaces step 5's single stage+commit: stage + and commit the pre-existing files as-is (`chore: import pre-existing content`), then stage + the stamped files and make the scaffold commit on top. The scaffold commit stays a pure, + reviewable RepoKit diff, and history records honestly that the content predates the + scaffold. +4. **Record it in ADR-0001:** the repo was scaffolded into a pre-populated directory, plus the + collision list, if any. + ## Steps 1. **Resolve the file set** (see `references/file-set-resolution.md`). diff --git a/plugins/repokit/skills/new-repo/references/placeholders.md b/plugins/repokit/skills/new-repo/references/placeholders.md index 620dbef..cceb4bc 100644 --- a/plugins/repokit/skills/new-repo/references/placeholders.md +++ b/plugins/repokit/skills/new-repo/references/placeholders.md @@ -6,7 +6,7 @@ | Token | Meaning | |-------|---------| -| `{{name}}` | repo / directory name (kebab-case) | +| `{{name}}` | repo / directory name (kebab-case by default; a deliberate branding name is an allowed exception, recorded in ADR-0001) | | `{{description}}` | one-line description | | `{{author}}` | author identity (default: the GitHub **handle**, `gh api user --jq .login`; a real personal name only on the user's explicit request — see the standard's *Author identity*) | | `{{license}}` | SPDX licence id (default `Apache-2.0`) | diff --git a/plugins/repokit/skills/repo-standard/standard/the-standard.md b/plugins/repokit/skills/repo-standard/standard/the-standard.md index f66c7e4..1c0ac26 100644 --- a/plugins/repokit/skills/repo-standard/standard/the-standard.md +++ b/plugins/repokit/skills/repo-standard/standard/the-standard.md @@ -140,6 +140,11 @@ many of these names are read by tools that require an exact case. follow the language/ecosystem idiom; never rename a convention-bearing file just to make the tree look uniform. +**Repo names:** `/new-repo` defaults to kebab-case, but a deliberate **branding name** (a +camelCase product name, say) is an allowed exception — the user's choice of their own product +name is not a style violation to argue with. Record the choice in ADR-0001 so an audit reads it +as a decision. + ## Author identity The **GitHub handle** (account or org login) identifies the author everywhere an