From 024f5272667ba31ae912e2d2139e88faafbe2742 Mon Sep 17 00:00:00 2001 From: Adam Dry Date: Sat, 14 Mar 2026 14:41:44 +0000 Subject: [PATCH] Adds migration guide for unique milestone IDs (#363) --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 3677dff82..6467bd353 100644 --- a/README.md +++ b/README.md @@ -371,6 +371,7 @@ Three specialized subagents for delegated work: The best practice for working in teams is to ensure unique milestone names across all branches (by using `unique_milestone_ids`) and checking in the right `.gsd/` artifacts to share valueable context between teammates. ### Suggested .gitignore setup + ```bash # ── GSD: Runtime / Ephemeral (per-developer, per-session) ────────────────── # Crash detection sentinel — PID lock, written per auto-mode session @@ -395,6 +396,7 @@ The best practice for working in teams is to ensure unique milestone names acros ### Unique Milestone Names Create or amend your `.gsd/preferences.md` file within the repo to include `unique_milestone_ids: true` e.g. + ```markdown --- version: 1 @@ -406,6 +408,14 @@ With the above `.gitignore` set up, the `.gsd/preferences.md` file is checked in Milestone names will now be generated with a 6 char random string appended e.g. instead of `M001` you'll get something like `M001-ush8s3` +### Migrating an existing git ignored `.gsd/` folder + +1. Ensure you are not in the middle of any milestones (clean state) +2. Update the `.gsd/` related entries in your `.gitignore` to follow the `Suggested .gitignore setup` section under `Working in teams` (ensure you are no longer blanket ignoring the whole `.gsd/` directory) +3. Update your `.gsd/preferences.md` file within the repo as per section `Unique Milestone Names` +4. If you want to update all your existing milestones use this prompt in GSD: `I have turned on unique milestone ids, please update all old milestone ids to use this new format e.g. M001-abc123 where abc123 is a random 6 char lowercase alpha numeric string. Update all references in all .gsd file contents, file names and directory names. Validate your work once done to ensure referential integrity.` +5. Commit to git + --- ## Architecture