Skip to main content

Adding a Project-Context Workspace

Plugin: TSH Product Management
Invoke: /tsh-product-management:adding-project-context-workspace (also model-invocable: it routes on "add a workspace for X", a new layer such as mobile or platform joining the project, or a topic outgrowing the workspace it sits in)
Used by: no skill or agent loads it. The knowledge base that Initializing Project Context scaffolds points to it from its root CLAUDE.md, its area map and conventions/ownership.md.

A workspace exists when a named person keeps an area current. The failure this skill prevents is a folder nobody owns: it fills up, goes stale, and becomes something readers cannot trust and will not delete.

What it covers​

AreaCoverage
Is it really new?Reads docs/README.md. If an existing workspace's scope covers the topic, even under another name (qa for quality, infra for platform), the answer is a document there, not a new folder, and the skill stops. A workspace is warranted when the area has its own standing content and its own owner
Exactly one ownerFull name and e-mail. The skill asks if it is not given and never infers it from git history or from who is talking. One person may own several workspaces. If nobody can be named yet, it stops: the workspace is created when somebody can be
The folderdocs/<name>/, kebab-case, with two files in the shape conventions/ownership.md defines and the wording of neighbouring workspaces
README.mdWhat the space holds, and what it does not, with a pointer to where that lives instead
CLAUDE.mdThe owner as default reviewer, scope, the rules a newcomer would get wrong, and where to start. It does not restate the root CLAUDE.md and holds no directory listing, because the README.md is the index
Area-map rowAdded to docs/README.md in the right table, project workspaces or layer workspaces. This is the step that gets forgotten, and a workspace missing from the map is invisible
DecisionsNo decisions/ folder inside the workspace. Records live in docs/decisions/ of the knowledge base and carry the workspace's name in their Scope
Splitting outWhen the workspace is split out of another, existing documents move in the same change and every link that pointed at them is fixed
Precedenceconventions/ownership.md of the knowledge base owns these rules and wins on any conflict

How it works​

  1. Locate the knowledge base. Resolve and sync KB through the shared guide and read KB/conventions/ownership.md. The branch is opened only once steps 2 and 3 say the workspace is warranted.
  2. Check it is really a new workspace.
  3. Get the owner.
  4. Open the branch and create the folder. Propose docs/workspace-<name> with write_worktree.py start, create it only after the person answers Create, and make every change under the worktree W, never in KB itself. Then create docs/<name>/README.md and CLAUDE.md.
  5. Add the row to the area map in W/docs/README.md.
  6. Verify, then commit and push only on a yes. Run both checker scripts from W until clean, then the Commit question (message docs: add the <name> workspace) and the Push question. The report lists the files created, the row added, the owner and the branch, and says the person opens the pull request from the link the push printed.

The branch, commit and push questions are the same as in Writing Project Knowledge: each git step runs only after its own yes, and the person's clone is never edited.

Rules​

SeverityRule
MUSTExactly one owner, named with full name and e-mail. Never two, never inferred
NEVERCreate the folder without both README.md and CLAUDE.md
MUSTAdd the area-map row in the same change as the folder
NEVERCreate a decisions/ folder inside the workspace
NEVERRestate the root CLAUDE.md in the workspace file, or put a directory listing there
MUSTMove existing documents into the new workspace in the same change when splitting one out, and fix every link that pointed at them

Source​