docs: rebrand to GSD Core and restructure docs with Diataxis (#605)
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
157
docs/how-to/work-in-parallel-with-workstreams.md
Normal file
157
docs/how-to/work-in-parallel-with-workstreams.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# How to work on multiple areas in parallel with workstreams
|
||||
|
||||
**Goal:** Run concurrent work on different milestone areas — backend API, frontend dashboard, infrastructure, or any other concern — without planning state from one area bleeding into another.
|
||||
|
||||
**Prerequisites:** An active GSD Core project (`.planning/ROADMAP.md` exists). If not, run `/gsd-new-project` first.
|
||||
|
||||
---
|
||||
|
||||
## What workstreams are
|
||||
|
||||
A workstream is an isolated planning context within a single codebase. Each workstream gets its own `.planning/workstreams/<name>/` subtree containing independent `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md`, and `phases/` directories. The codebase itself — source code, git history, and branches — is shared across all workstreams.
|
||||
|
||||
```
|
||||
.planning/
|
||||
├── PROJECT.md ← shared
|
||||
├── config.json ← shared
|
||||
├── codebase/ ← shared
|
||||
└── workstreams/
|
||||
├── backend-api/
|
||||
│ ├── STATE.md
|
||||
│ ├── ROADMAP.md
|
||||
│ ├── REQUIREMENTS.md
|
||||
│ └── phases/
|
||||
└── frontend-dash/
|
||||
├── STATE.md
|
||||
├── ROADMAP.md
|
||||
├── REQUIREMENTS.md
|
||||
└── phases/
|
||||
```
|
||||
|
||||
When a workstream is active, every GSD command — `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase` — reads from and writes to that workstream's directory. Switching workstreams redirects all of those commands to a different subtree without touching the source tree.
|
||||
|
||||
---
|
||||
|
||||
## Create a workstream
|
||||
|
||||
```bash
|
||||
/gsd-workstreams create backend-api
|
||||
```
|
||||
|
||||
GSD creates the workstream directory under `.planning/workstreams/backend-api/` and seeds it with a skeleton `STATE.md` and `ROADMAP.md`. The workstream is not automatically activated — you switch to it explicitly.
|
||||
|
||||
---
|
||||
|
||||
## List workstreams
|
||||
|
||||
```bash
|
||||
/gsd-workstreams list
|
||||
```
|
||||
|
||||
Shows all workstreams and which one is currently active in your session.
|
||||
|
||||
---
|
||||
|
||||
## Switch to a workstream
|
||||
|
||||
```bash
|
||||
/gsd-workstreams switch backend-api
|
||||
```
|
||||
|
||||
From this point forward, all GSD workflow commands operate in the `backend-api` context. The switch is session-scoped: when multiple Claude Code terminals are open on the same repo, each session can hold a different active workstream without interfering with the others.
|
||||
|
||||
Once switched, drive the normal phase workflow:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 1
|
||||
/gsd-plan-phase 1
|
||||
/gsd-execute-phase 1
|
||||
/gsd-verify-work 1
|
||||
```
|
||||
|
||||
To work on another area, switch workstreams in a second terminal:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams switch frontend-dash
|
||||
/gsd-discuss-phase 1
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Check progress across all workstreams
|
||||
|
||||
```bash
|
||||
/gsd-workstreams progress
|
||||
```
|
||||
|
||||
Prints a cross-workstream summary — phase status, current position, and outstanding work for every workstream — without requiring you to switch between them.
|
||||
|
||||
For detailed status on a single workstream:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams status backend-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resume work in a workstream
|
||||
|
||||
After a context reset or a new session, restore your position:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams resume backend-api
|
||||
```
|
||||
|
||||
This activates the workstream and restores your last known position within it, equivalent to switching and then running `/gsd-resume-work`.
|
||||
|
||||
---
|
||||
|
||||
## Archive a completed workstream
|
||||
|
||||
When a workstream's milestone work is done:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams complete backend-api
|
||||
```
|
||||
|
||||
GSD marks the workstream as archived and moves it out of the active listing. The planning artifacts are preserved under `.planning/workstreams/backend-api/` for audit purposes.
|
||||
|
||||
---
|
||||
|
||||
## Scope a single command to a workstream without switching
|
||||
|
||||
If you need to run one command against a specific workstream without changing your session's active context, use the `--ws` flag:
|
||||
|
||||
```bash
|
||||
/gsd-progress --ws frontend-dash
|
||||
/gsd-plan-phase 2 --ws backend-api
|
||||
```
|
||||
|
||||
`--ws` takes highest priority in the resolution order and does not alter the session-scoped pointer.
|
||||
|
||||
---
|
||||
|
||||
## When to use workstreams instead of workspaces
|
||||
|
||||
Choose workstreams when:
|
||||
|
||||
- All the work lives in the **same repository** and shares the same git history
|
||||
- You want to plan or discuss different concern areas (API, UI, infra) **concurrently** without one workstream's `STATE.md` overwriting another's
|
||||
- You do not need a separate branch per workstream at creation time (though you can branch as normal within each workstream's execution)
|
||||
- The overhead of creating full git worktrees is not justified by the isolation you need
|
||||
|
||||
Choose [workspaces](isolate-work-with-workspaces.md) instead when:
|
||||
|
||||
- You are working across **multiple repositories** (e.g., `hr-ui` and `ZeymoAPI`)
|
||||
- You need the isolation of a **separate git worktree** or clone per feature — fully independent branches, lock files, and build artefacts
|
||||
- You want to run `/gsd-new-project` independently in each workspace with a wholly separate `.planning/` root, not a subdirectory of the main repo's `.planning/`
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Isolate work with workspaces](isolate-work-with-workspaces.md)
|
||||
- [The phase loop](../explanation/the-phase-loop.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [docs index](../README.md)
|
||||
Reference in New Issue
Block a user