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:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions

View 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)