From ed2f6a8c6c5587c960e01709806934948fcb717d Mon Sep 17 00:00:00 2001 From: PBNZ <93853627+PBNZ@users.noreply.github.com> Date: Thu, 13 Aug 2026 19:33:04 +1200 Subject: [PATCH] docs(new-repo): adopting a pre-populated directory + the branding-name exception (refs #33) Two gaps a scaffolding session had to improvise around. The skill now documents scaffolding into a directory that already has content: inventory first (an existing .git means retrofit, not scaffold), pre-existing content wins collisions, and two commits with the import before the scaffold so the RepoKit diff stays pure. And the kebab-case default now states its exception: a deliberate branding name is the user's choice, accepted and recorded in ADR-0001 - stated in the standard's naming conventions, the interview inputs, and the placeholder reference. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_013g4xpqBjwwzfqtKyEHuWUr --- CHANGELOG.md | 9 +++++++ docs/CHECKPOINT.md | 10 +++++--- plugins/repokit/skills/new-repo/SKILL.md | 25 ++++++++++++++++++- .../new-repo/references/placeholders.md | 2 +- .../repo-standard/standard/the-standard.md | 5 ++++ 5 files changed, 45 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 68221f8..dd79b17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- 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 ### Added diff --git a/docs/CHECKPOINT.md b/docs/CHECKPOINT.md index b34f4e5..83eea62 100644 --- a/docs/CHECKPOINT.md +++ b/docs/CHECKPOINT.md @@ -4,9 +4,11 @@ Resume state: what a fresh session needs to pick this repo up. Keep every line c pre-commit checklist has the tripwire, and stale entries are worse than none. - Last updated: 2026-08-13 -- Status: DONE -- In progress: nothing — author-identity + branch-hygiene batch (#25/#26/#28, PRs #29/#30, - ADR-0009) merged and closed; release 0.6.0 cut; `delete-branch-on-merge` enabled on the repo -- Next step: paused — nothing pending +- Status: IN PROGRESS +- In progress: scaffolding field-report batch #31/#32/#33/#34 — four local branches ready for + review (`fix/31-planned-start-here-paths`, `docs/33-adopt-existing-dir-and-branding`, + `feat/32-early-licence-optin`, `feat/34-privacy-guard`; ADR-0010/0011/0012) +- Next step: review the four branches locally, push, open one PR each (`Refs #NN`), merge in + numeric order resolving trivial `CHANGELOG.md` [Unreleased] overlaps, verify each issue, close One line per fact, current state only — history lives in `CHANGELOG.md` and git. 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 c2fa315..d9f81f6 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