Workspaces
A workspace is a git repo you clone to stand up a whole job to be done. A job is one cross-repo feature that touches several of your projects. The workspace repo carries the manifest and the job's wiki. The manifest names which member repos belong to the job, where to clone them from, and which project is the focus. The member repos themselves materialize beside them, and the workspace repo never tracks them.
~/workspaces/myapp/ ← THE WORKSPACE REPO — this folder is what
you clone, commit, and push
.shipd-config.json ← manifest: focus + projects + clone urls (tracked)
.gitignore ← members block, engine-managed (tracked)
.shipd/
wiki/ ← the job's knowledge store (tracked)
initiatives/ projects/ ← goals & per-project context (tracked)
api/ web/ mobile/ ← member repos, machine-local (ignored)
One folder per job, all of them under a ~/workspaces/ parent. The leaf
carries the job's name (myapp), never a member repo's name. That
keeps it distinct from the api/ checkout materialized inside it.
Everything marked (tracked) travels with git clone. The sync ladder
rebuilds everything marked (ignored) per machine. It prefers worktrees or
reference-clones of repos you already have locally, and clones in full only on
a fresh machine.
The guide
Getting started — machine setup, creating a job workspace, checking it into git, loading it on another machine, and the day-to-day verbs.
shipd workspace init myapp --git
The member map and discovery — mapping a member to a checkout you already have, and resolving the workspace from outside it.
shipd workspace # repo: shipd [mapped -> /Users/you/projects/shipd]
Nesting and external stores — filing a job workspace beneath a base one so
it inherits the base's knowledge, and relocating artifacts with store_root.
shipd workspace init ~/workspaces/acme-base/myapp --nested --git
Sharing a workspace with a team — several engineers on one workspace repo, what travels between them, the hooks consent gate, and conflict surfaces. The blessed enterprise layout nests one team workspace per team under one base.
shipd doctor # store-sync — how far your clone has drifted
Headless consumers — the minimal footprint a CI job, bot, or cloud agent needs to read a workspace without members, git, or machine config.
python3 <plugin>/skills/build/scripts/spec_status.py --root /tmp/ws workspace-show
Practical examples: multi-workspace repos — the blessed shape for
carrying several team workspaces in one repo. A base workspace holds a
--nested team workspace per team, shown with a layout tree and a storage
table.
git clone git@github.com:acme/workspaces.git ~/workspaces/acme-base
cd ~/workspaces/acme-base/myapp && shipd workspace sync