msd-core/docs/how-to/keep-planning-docs-private.md

Keep planning docs out of a shared repo

You are working in a team repo and want GSD's .planning/ artifacts — PLAN.md, SUMMARY.md, ROADMAP.md, STATE.md — to stay on your machine instead of appearing in commits your teammates read.

This takes four steps, and the third is the one people miss.

1. Turn off doc commits

gsd-tools config-set planning.commit_docs false

gsd-tools query commit now returns a skipped envelope instead of committing, and every workflow that writes a planning artifact honors it.

2. Ignore the directory

Add to .gitignore:

.planning/

This is also enough on its own: when .planning/ is gitignored and config.json sets no explicit value, GSD auto-resolves commit_docs to false. Setting it explicitly in step 1 is clearer, and it survives someone later editing .gitignore.

3. Untrack what git is already tracking

This is the step that catches people out. .gitignore only stops git picking up new files. It has no effect on files already committed — git keeps tracking those, so git add -A keeps staging them even though steps 1 and 2 are both done.

Because GSD's default is commit_docs: true, most existing projects already have .planning/ in history, which makes this the common case rather than an edge case.

git rm -r --cached .planning/
git commit -m "chore: stop tracking planning docs"

--cached removes the files from the index only — your files on disk are untouched.

To check whether this applies to you before running it:

git ls-files .planning

Any output means git is still tracking those paths.

4. Keep search working

With .planning/ ignored, tools that respect .gitignore stop searching it — including GSD's own broad searches, which is rarely what you want, since the planning docs are exactly what you want an agent to read.

gsd-tools config-set planning.search_gitignored true

This adds --no-ignore to broad searches so .planning/ is still found locally.

Verify

gsd-tools validate health

A clean result means you are done. If you skipped step 3, you will see:

W029  .planning/ is gitignored but N file(s) are still tracked by git
      Fix: git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"

W029 is advisory. GSD will not untrack files for you, and --repair deliberately does not act on it — removing files from the index is destructive and the timing is yours.

Notes

• A deliberate force-add also raises W029. If you intentionally keep one file tracked under an otherwise-ignored .planning/ (git add -f .planning/decisions.md), the warning still appears. There is no reliable way to tell an intentional force-add from the accidental case, so the warning is expected there too.
• Teammates who have already pulled the tracked files will see them deleted by your step-3 commit. That is the intended effect — the files leave the repo, not their working copies of your branch — but say so in the commit message or PR description so it is not a surprise.

Per-phase override

You just made the whole project local-only in step 1. If instead you want ONE phase's artifacts — say, an architecture or ADR phase whose PLAN.md and REQUIREMENTS.md are worth sharing with the team — committed while every other phase stays local, set a phase_commit_docs entry for that phase's number instead of (or on top of) the project-wide switch:

gsd-tools config-set planning.commit_docs false
gsd-tools config-set phase_commit_docs.03 true

{
  "planning": { "commit_docs": false },
  "phase_commit_docs": { "03": true }
}

Now gsd-tools query commit commits phase 03's artifacts normally, and skips (with the skipped_commit_docs_phase_false-or-skipped_commit_docs_false reason depending on which tier decided) every other phase's — the project-wide setting from step 1 still governs everything phase_commit_docs does not name.

A few things worth knowing before you rely on this:

• The phase-id form doesn't matter. phase_commit_docs.3, phase_commit_docs.03, and (if your project uses a project_code) phase_commit_docs.PROJ-03 all resolve to the same entry — GSD normalizes the phase number before lookup, the same way it does everywhere else phase numbers are compared.
• It only applies to a commit that names a phase-scoped file. gsd-tools query commit resolves the phase from the --files paths you pass it (via the .planning/phases/<phase-dir>/… segment). A commit that names no phase file — e.g. a bare ROADMAP.md update — has no phase to look up, so phase_commit_docs never applies to it and the project-wide setting governs, same as before this feature existed.
• It's per phase, not per artifact. You cannot commit a phase's ADR but suppress its SUMMARY within the same commit; the override applies to the whole phase.
• Reverse direction works too. With the project-wide default (commit_docs: true), set phase_commit_docs.<phase-id> false to suppress just one noisy execution phase while everything else commits normally.

Full precedence order (highest wins): phase_commit_docs.<phase-id> → explicit commit_docs / planning.commit_docs → .gitignore auto-detect → the manifest default. See Configuration reference — per-phase override for the complete rules, including how a non-boolean value is handled.

Related

• Configuration reference — planning.commit_docs
• Configuration reference — auto-detection and the tracked-files caveat
• Configuration reference — per-phase override