From c2158b96906bdbbe099f047a87adf1589a44d72d Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Fri, 17 Apr 2026 10:15:47 -0400 Subject: [PATCH] docs(contributing): clarify agents/ source of truth vs install-sync targets (#2365) (#2366) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents that only agents/ at the repo root is tracked by git. .claude/agents/, .cursor/agents/, and .github/agents/ are gitignored install-sync outputs and must not be edited — they will be overwritten. Closes #2365 Co-authored-by: Claude Opus 4.7 --- CONTRIBUTING.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50024d598..3fff4ff4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -316,13 +316,25 @@ get-shit-done/ workflows/ — Workflow definitions (.md) references/ — Reference documentation (.md) templates/ — File templates -agents/ — Agent definitions (.md) +agents/ — Agent definitions (.md) — CANONICAL SOURCE commands/gsd/ — Slash command definitions (.md) tests/ — Test files (.test.cjs) helpers.cjs — Shared test utilities docs/ — User-facing documentation ``` +### Source of truth for agents + +Only `agents/` at the repo root is tracked by git. The following directories may exist on a developer machine with GSD installed and **must not be edited** — they are install-sync outputs and will be overwritten: + +| Path | Gitignored | What it is | +|------|-----------|------------| +| `.claude/agents/` | Yes (`.gitignore:9`) | Local Claude Code runtime sync | +| `.cursor/agents/` | Yes (`.gitignore:12`) | Local Cursor IDE bundle | +| `.github/agents/gsd-*` | Yes (`.gitignore:37`) | Local CI-surface bundle | + +If you find that `.claude/agents/` has drifted from `agents/` (e.g., after a branch change), re-run `bin/install.js` to re-sync from the canonical source. Always edit `agents/` — never the derivative directories. + ## Security - **Path validation** — use `validatePath()` from `security.cjs` for any user-provided paths