msd-core/docs/how-to/isolate-work-with-workspaces.md

How to isolate work with workspaces

Goal: Create a fully isolated GSD environment — separate git worktree, independent .planning/ root, and optionally multiple repositories — for feature branches or multi-repo work.

Prerequisites: git is installed and the repository supports worktrees. For multi-repo workspaces, the target repos exist on your local machine or are accessible by path.

---

What workspaces are

A workspace is a self-contained environment that pairs one or more git worktrees (or clones) with its own .planning/ root directory. Each workspace has:

• Its own .planning/ directory that is completely independent from the source repo's .planning/ — not a subdirectory of it
• Its own WORKSPACE.md manifest tracking member repos
• Git worktrees (default) or full clones of the specified repos, checked out on a dedicated branch (default: workspace/<name>)

Workspaces live under ~/gsd-workspaces/<name>/ by default.

~/gsd-workspaces/
└── feature-b/
    ├── WORKSPACE.md        ← manifest
    ├── .planning/          ← fully independent GSD state
    │   ├── PROJECT.md
    │   ├── ROADMAP.md
    │   └── ...
    ├── hr-ui/              ← worktree or clone of hr-ui repo
    └── ZeymoAPI/           ← worktree or clone of ZeymoAPI repo

Because the workspace's .planning/ is separate from the source repos, there is no overlap or conflict with planning state that exists in the source repos themselves.

---

Create a workspace for multiple repos

/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI

GSD creates worktrees of hr-ui and ZeymoAPI inside ~/gsd-workspaces/feature-b/, checks out a workspace/feature-b branch in each, writes WORKSPACE.md, and creates an empty .planning/ directory ready for /gsd-new-project.

To customise the location:

/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b

---

Create a workspace for the current repo

When you want feature-branch isolation on a single repo — independent branch, independent .planning/, no state bleed from main:

/gsd-workspace --new --name payments-rework --repos .

The . tells GSD to create a worktree of the current repo. The worktree is checked out on workspace/payments-rework.

To force a full clone instead of a worktree:

/gsd-workspace --new --name payments-rework --repos . --strategy clone

---

Specify a branch explicitly

/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2

The --branch flag sets the branch name for all repos in the workspace. Defaults to workspace/<name>.

---

Skip interactive questions

/gsd-workspace --new --name payments-rework --repos . --auto

GSD accepts all defaults without prompting.

---

Initialise GSD inside the workspace

After creating a workspace, move into it and initialise a GSD project:

cd ~/gsd-workspaces/feature-b
/gsd-new-project

The .planning/ directory inside the workspace is the root for all subsequent GSD commands run from that directory. It is entirely separate from any .planning/ that exists in the source repos.

---

List workspaces

/gsd-workspace --list

Prints all active GSD workspaces and their status.

---

Remove a workspace

/gsd-workspace --remove feature-b

GSD removes the git worktrees and cleans up the workspace directory. This does not delete the branches from the origin remote — only the local worktrees and workspace directory.

---

When to use workspaces instead of workstreams

Choose workspaces when:

• You are working across multiple repositories that need to be co-ordinated under one GSD project (e.g., an API repo and a UI repo that ship together)
• You need a separate git worktree with its own branch, lock files, and build artefacts per feature — so builds and dependency installs in one environment cannot affect another
• You want a wholly independent .planning/ root rather than a subdirectory of the main repo's .planning/
• You are following an issue-driven workflow where each tracker issue maps to a workspace (see Drive GSD from a tracker issue)

Choose workstreams instead when:

• All the work lives in one repository and shares the same git history
• You want to run /gsd-plan-phase or /gsd-discuss-phase on different concern areas concurrently — API, UI, infra — without context bleed between their STATE.md files
• You do not need a separate worktree per concern; switching planning context is sufficient

---

Related

• Work in parallel with workstreams
• Drive GSD from a tracker issue
• Commands
• docs index