b6b74d4ccf
* docs: add monorepo guide Adds docs/guides/monorepo.md covering per-project .specify/, targeting a member project from the repo root with SPECIFY_INIT_DIR, agent env propagation, the git extension scoping limitation (#3081), and per-project constitutions. Wires it into docs/toc.yml under Development. * docs: correct monorepo Git guidance * docs: drop open-issue reference and polish monorepo guide prose * docs: fix SPECIFY_INIT_DIR error example (absolute path, non-project dir) * docs: address Copilot wording nits in monorepo guide * docs: clarify monorepo constitution sharing Assisted-by: Codex (model: GPT-5, autonomous)
4.5 KiB
Using Spec Kit in a Monorepo
A Spec Kit project is directory-scoped: the project is whichever directory
contains .specify/. A monorepo can hold several independent Spec Kit projects
under one repository root, each with its own .specify/, specs/, constitution,
and feature numbering.
Root resolution already prefers the nearest .specify/ over the Git
toplevel, so commands run from inside a member project resolve to that project,
not the repo root.
Layout
my-monorepo/
├── .git/ # one Git repository at the root
├── apps/
│ ├── web/
│ │ └── .specify/ # Spec Kit project "web"
│ │ └── memory/constitution.md
│ └── api/
│ └── .specify/ # Spec Kit project "api"
│ └── memory/constitution.md
└── packages/
└── ui/
└── .specify/ # Spec Kit project "ui"
Initialize each member project independently:
specify init apps/web --integration claude
specify init apps/api --integration claude
Each project keeps its own specs/ directory and numbers features
independently (apps/web/specs/001-…, apps/api/specs/001-…).
Working inside a member project
The default workflow is unchanged: change into the project directory and run the
slash commands. Root resolution finds the nearest .specify/.
cd apps/web
# then run /speckit.specify, /speckit.plan, … in your agent
Targeting a member project from the repo root
For non-interactive or CI runs where you do not want to cd, set
SPECIFY_INIT_DIR to the member project root (the directory containing
.specify/). Relative paths resolve against the current directory.
# operate on apps/web from the monorepo root (no cd required)
export SPECIFY_INIT_DIR=apps/web
The path must exist and contain .specify/. If it does not, the command
errors and does not fall back to the current directory or the Git toplevel.
This is deliberate: a typo never writes specs into the wrong project. A
nonexistent path is reported as you typed it; a path that exists but is not a
Spec Kit project is reported as its resolved absolute path:
# SPECIFY_INIT_DIR=apps/wbe (typo: no such directory)
ERROR: SPECIFY_INIT_DIR does not point to an existing directory: apps/wbe
# SPECIFY_INIT_DIR=apps (exists, but has no .specify/ of its own)
ERROR: SPECIFY_INIT_DIR is not a Spec Kit project (no .specify/ directory): /home/you/my-monorepo/apps
SPECIFY_INIT_DIR selects the project; SPECIFY_FEATURE_DIRECTORY selects
the feature within it. They compose: set both to pick a project and a
feature non-interactively. See the
SPECIFY_INIT_DIR reference for
the full contract and the two-axes model.
How SPECIFY_INIT_DIR reaches your agent
SPECIFY_INIT_DIR is read by the shell scripts that the slash commands invoke
(get_repo_root in Bash, Get-RepoRoot in PowerShell). It takes effect only
when it is present in the environment of the shell that runs those scripts.
- Scripted / CI runs: export it in the same shell that drives the commands; it is reliable there.
- Interactive agents: whether an exported variable reaches the shell tool an
agent uses is agent-specific. Export
SPECIFY_INIT_DIRbefore launching the agent, and verify once (e.g. run/speckit.specifyand confirm the new feature landed under the intended project'sspecs/).
Git in a monorepo
Note
Spec Kit project files are scoped to the resolved project root, but Git operations still run in the containing Git work tree. In a monorepo with a single Git repository at the root and projects in subdirectories, feature branch creation creates or switches branches in the shared root repository. Spec directories still live under the selected member project, while the Git branch namespace is shared by the whole monorepo. Manage branches and commits at the repository root, or initialize Git per member project if you want isolated per-project branch namespaces.
Constitutions
Each member project has its own .specify/memory/constitution.md and
/speckit.constitution edits the local project's file. Spec Kit does not provide
a built-in base/inheritance mechanism; if you want one constitution to reference
shared rules elsewhere in the monorepo, you need to maintain that wiring yourself.
Otherwise, duplicate or sync shared engineering rules per project.