Clarifying GSD project, repository, worktree, and workspace boundaries

[deinspanjer]

I’m trying to understand the intended GSD model for developers working on gsd-core itself, particularly when using ordinary Git worktrees for isolated changes.

My current understanding is that a GSD “project” is an initiative: a bounded set of goals, requirements, roadmap phases, and planning state that may involve one or more repositories. In more conventional product-development language, I would often call this an initiative or epic.

That differs from how “project” is commonly used by agent harnesses such as Codex and Claude Code. There, a project is primarily the filesystem/configuration context in which the agent operates—usually one repository, but potentially a monorepo or directory containing several repositories.

The distinction becomes difficult in a repository like gsd-core:

• Multiple developers may be working on unrelated fixes or features.
• One developer may have several unrelated changes in progress.
• Git worktrees and branches are a familiar way to isolate those changes.
• The repo does not commit .planning/, so a worktree does not automatically carry the GSD planning state associated with another checkout.

In the worktree I am using, GSD sees no local .planning/ and resolves planning commands back to the primary checkout’s planning root. That may be a deliberate model, but it is surprising: a command launched from an isolated Git worktree can operate on planning state outside that worktree.

This leaves me unsure which of these is the intended workflow:

1. Keep one shared GSD project/planning state in the primary checkout, while using Git worktrees only for source changes.
2. Create a separate GSD project for each independent initiative, even when all work is in the same repository.
3. Use GSD workstreams for independent initiatives, while keeping source work in manually managed Git worktrees.
4. Use $gsd-workspace --new whenever planning state needs isolation as well as source isolation.
5. Avoid GSD lifecycle commands for small, self-contained bug fixes.

I am not suggesting that all of these need to be supported equally. The main request is for a clearer conceptual model and a documented decision guide for this common case.

A few things that would make the behavior easier to understand:

• Explicit terminology distinguishing a GSD initiative/project, a repository, a Git worktree, and a GSD workspace.
• A documented recommended pattern for independent changes in one repository.
• A clear warning when a command invoked from a linked worktree will operate on another checkout’s .planning/ directory.
• Guidance on when a normal Git worktree is sufficient versus when a GSD workspace or workstream is appropriate.

The current behavior may be internally consistent, but the implicit handoff from “this checkout” to “the primary planning checkout” is difficult to predict without reading implementation details.