Skip to content

docs: add plan-PR-then-execute workflow to team guide #3446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
murataslan1 wants to merge 1 commit into
base: main
Choose a base branch
from
+31 −0
Open

docs: add plan-PR-then-execute workflow to team guide #3446

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/working-in-teams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<MID>/` (`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.
Comment on lines +89 to +91
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Plan PR step lists planning artifacts as .gsd/milestones/<MID>/ (CONTEXT.md, ROADMAP.md, updated REQUIREMENTS.md, DECISIONS.md), but the actual filenames/locations differ: milestone artifacts are {MID}-CONTEXT.md and {MID}-ROADMAP.md inside .gsd/milestones/{MID}/, while REQUIREMENTS/DECISIONS are top-level .gsd/REQUIREMENTS.md and .gsd/DECISIONS.md. Consider updating the wording to reflect the real paths so reviewers know what to expect in the plan PR diff.

Copilot uses AI. Check for mistakes.

This works because `/gsd discuss` does not auto-commit — the developer controls when and how planning artifacts are committed.
Comment on lines +87 to +93
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section says teams can commit discuss artifacts for review, but the discuss/guided planning prompts currently include a commit instruction that explicitly says "Do not commit planning artifacts — .gsd/ is managed externally." That conflicts with the workflow described here and may confuse users following the on-screen instructions. Either reconcile the docs with the current prompt instruction, or clarify when/why it’s safe/expected to commit .gsd/ artifacts in team mode (e.g., when git.commit_docs: true).

Suggested change
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/<MID>/` (`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.
Teams can use a two-PR cycle to get plan approval before any code is written, **if their repository is configured to track planning artifacts in git** (for example, when `git.commit_docs: true` and `.gsd/milestones/` is not gitignored):
1. **Plan PR** — developer runs `/gsd discuss` on `main`, which writes planning artifacts to `.gsd/milestones/<MID>/` (`CONTEXT.md`, `ROADMAP.md`, updated `REQUIREMENTS.md`, `DECISIONS.md`). If your team commits planning docs, 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.
`/gsd discuss` does not auto-commit — the developer controls when and how planning artifacts are shared. If the prompt says not to commit planning artifacts because `.gsd/` is managed externally, follow that instruction and review/share the plan outside git instead of opening a docs-only PR.

Copilot uses AI. Check for mistakes.

### 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.

Comment on lines +103 to +104
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text implies /gsd steer changes stay local to the execution worktree, but /gsd steer writes the override to .gsd/OVERRIDES.md in the current working directory (and can therefore modify the main working copy if run there). Consider tightening the wording to specify that steering is local only when invoked from within the auto-mode worktree, and that it updates OVERRIDES.md / plan docs that will appear in the code PR diff.

Suggested change
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 during execution, those adjustments remain local to that worktree rather than changing the main working copy. `/gsd steer` writes to `.gsd/OVERRIDES.md` in the current working directory, so running it outside the auto-mode worktree can modify whichever checkout it is run from.
Steering can also update `OVERRIDES.md` and related planning artifacts in the execution worktree, and those changes may appear in the code PR diff for reviewers alongside the implementation.

Copilot uses AI. Check for mistakes.
### 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.
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The require_slice_discussion description says it “pauses auto-mode before each slice begins” for review, but the implementation pauses only when a slice lacks a slice CONTEXT file and instructs the user to run /gsd discuss for that slice before resuming. Consider updating this description to reflect the actual gate condition (missing slice context) and the required action to proceed.

Suggested change
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.

Copilot uses AI. Check for mistakes.

## Parallel Development

Multiple developers can run auto mode simultaneously on different milestones. Each developer:
Expand Down
Loading