From c08388fbcd010cc294d6cc206af8a4c3c18705cb Mon Sep 17 00:00:00 2001 From: Murat Aslan Date: Fri, 3 Apr 2026 15:59:07 +0300 Subject: [PATCH 1/2] docs: add plan-PR-then-execute workflow to working-in-teams guide Document the two-PR cycle where teams review planning artifacts before any code is written. Covers what reviewers should look for, how steering during execution stays local, and the require_slice_discussion gate. Closes #3363 --- docs/working-in-teams.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/working-in-teams.md b/docs/working-in-teams.md index fd5476813b..c7d90e20f3 100644 --- a/docs/working-in-teams.md +++ b/docs/working-in-teams.md @@ -82,6 +82,37 @@ If you have an existing project with `.gsd/` blanket-ignored: ``` 5. Commit +## Plan Review Workflow + +Teams can use a two-PR cycle to get plan approval before any code is written: + +1. **Plan PR** — developer runs `/gsd discuss` on `main`, which writes planning artifacts to `.gsd/milestones//` (`CONTEXT.md`, `ROADMAP.md`, updated `REQUIREMENTS.md`, `DECISIONS.md`). The developer commits these and opens a docs-only PR. +2. **Review** — the team reviews scope, risks, slice breakdown, and definition of done directly in GitHub. No code to review yet, just the plan. +3. **Code PR** — after the plan PR is merged, the developer pulls `main` and runs `/gsd auto`. GSD creates a worktree and executes against the approved plan. The result is a second PR with the actual implementation. + +This works because `/gsd discuss` does not auto-commit — the developer controls when and how planning artifacts are committed. + +### What reviewers should look for + +- **`CONTEXT.md`** — is the scope well-defined? Are constraints and non-goals clear? +- **`ROADMAP.md`** — does the slice breakdown make sense? Are slices ordered by dependency? +- **`DECISIONS.md`** — are the architectural choices justified? + +### Steering during execution + +If the developer uses `/gsd steer` during execution, those adjustments stay local to the worktree and don't modify the approved plan docs on `main`. The code PR diff will reflect any deviations. + +### Automated gates + +For teams that want a review checkpoint before each slice (not just the milestone), add `require_slice_discussion: true` to preferences: + +```yaml +phases: + require_slice_discussion: true +``` + +This pauses auto-mode before each slice begins, giving the developer a chance to review the slice context before proceeding. + ## Parallel Development Multiple developers can run auto mode simultaneously on different milestones. Each developer: From 6c41e01f4af64f1114e4f615963891ae4ce1be9d Mon Sep 17 00:00:00 2001 From: Murat Aslan Date: Tue, 7 Apr 2026 07:51:23 +0300 Subject: [PATCH 2/2] docs: fix artifact paths, commit_docs context, steer scope, and slice gate description --- docs/working-in-teams.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/working-in-teams.md b/docs/working-in-teams.md index c7d90e20f3..074f508391 100644 --- a/docs/working-in-teams.md +++ b/docs/working-in-teams.md @@ -84,34 +84,34 @@ If you have an existing project with `.gsd/` blanket-ignored: ## Plan Review Workflow -Teams can use a two-PR cycle to get plan approval before any code is written: +Teams configured to track planning artifacts in git (i.e. with `mode: team` and `.gsd/milestones/` not gitignored) can use a two-PR cycle to get plan approval before any code is written: -1. **Plan PR** — developer runs `/gsd discuss` on `main`, which writes planning artifacts to `.gsd/milestones//` (`CONTEXT.md`, `ROADMAP.md`, updated `REQUIREMENTS.md`, `DECISIONS.md`). The developer commits these and opens a docs-only PR. +1. **Plan PR** — developer runs `/gsd discuss` on `main`, which writes planning artifacts to `.gsd/milestones//` (milestone files `-CONTEXT.md` and `-ROADMAP.md`) and updates the top-level `.gsd/REQUIREMENTS.md` and `.gsd/DECISIONS.md`. The developer commits these and opens a docs-only PR. 2. **Review** — the team reviews scope, risks, slice breakdown, and definition of done directly in GitHub. No code to review yet, just the plan. 3. **Code PR** — after the plan PR is merged, the developer pulls `main` and runs `/gsd auto`. GSD creates a worktree and executes against the approved plan. The result is a second PR with the actual implementation. -This works because `/gsd discuss` does not auto-commit — the developer controls when and how planning artifacts are committed. +`/gsd discuss` does not auto-commit — the developer controls when and how planning artifacts are committed. ### What reviewers should look for -- **`CONTEXT.md`** — is the scope well-defined? Are constraints and non-goals clear? -- **`ROADMAP.md`** — does the slice breakdown make sense? Are slices ordered by dependency? -- **`DECISIONS.md`** — are the architectural choices justified? +- **`-CONTEXT.md`** — is the scope well-defined? Are constraints and non-goals clear? +- **`-ROADMAP.md`** — does the slice breakdown make sense? Are slices ordered by dependency? +- **`.gsd/DECISIONS.md`** — are the architectural choices justified? ### Steering during execution -If the developer uses `/gsd steer` during execution, those adjustments stay local to the worktree and don't modify the approved plan docs on `main`. The code PR diff will reflect any deviations. +If the developer uses `/gsd steer` from within the auto-mode worktree, those adjustments remain local to that worktree and write to `.gsd/OVERRIDES.md` in the worktree — they don't modify the approved plan docs on `main`. These changes will appear in the code PR diff alongside the implementation. Running `/gsd steer` outside the worktree modifies whichever checkout it is run from. ### Automated gates -For teams that want a review checkpoint before each slice (not just the milestone), add `require_slice_discussion: true` to preferences: +For teams that want a required discussion checkpoint before each slice (not just the milestone), add `require_slice_discussion: true` to preferences: ```yaml phases: require_slice_discussion: true ``` -This pauses auto-mode before each slice begins, giving the developer a chance to review the slice context before proceeding. +This pauses auto-mode when a slice is missing its slice `CONTEXT` file and requires the developer to run `/gsd discuss` for that slice before proceeding. ## Parallel Development