π« Toolkit to help you get started with SDD or any other process!
docs: add monorepo guide (#3084)
Pascal THUETb6b74d4ccf8a
diff --git a/docs/guides/monorepo.md b/docs/guides/monorepo.mdnew file mode 100644index 000000000..b14369925--- /dev/null+++ b/docs/guides/monorepo.md@@ -0,0 +1,111 @@+# 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++```text+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:++```bash+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/`.++```bash+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.++```bash+# 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:++```text+# 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](../reference/core.md#environment-variables) 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_DIR` *before* launching the+ agent, and verify once (e.g. run `/speckit.specify` and confirm the new feature+ landed under the intended project's `specs/`).++## 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.diff --git a/docs/toc.yml b/docs/toc.ymlindex aba93ab43..711abb337 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -53,6 +53,8 @@href: local-development.md- name: Evolving Specshref: guides/evolving-specs.md+ - name: Monorepos+ href: guides/monorepo.md# Community- name: Community