|
| 1 | +# Using Spec Kit in a Monorepo |
| 2 | + |
| 3 | +A Spec Kit project is **directory-scoped**: the project is whichever directory |
| 4 | +contains `.specify/`. A monorepo can hold several independent Spec Kit projects |
| 5 | +under one repository root, each with its own `.specify/`, `specs/`, constitution, |
| 6 | +and feature numbering. |
| 7 | + |
| 8 | +Root resolution already prefers the **nearest** `.specify/` over the Git |
| 9 | +toplevel, so commands run from inside a member project resolve to that project, |
| 10 | +not the repo root. |
| 11 | + |
| 12 | +## Layout |
| 13 | + |
| 14 | +```text |
| 15 | +my-monorepo/ |
| 16 | +├── .git/ # one Git repository at the root |
| 17 | +├── apps/ |
| 18 | +│ ├── web/ |
| 19 | +│ │ └── .specify/ # Spec Kit project "web" |
| 20 | +│ │ └── memory/constitution.md |
| 21 | +│ └── api/ |
| 22 | +│ └── .specify/ # Spec Kit project "api" |
| 23 | +│ └── memory/constitution.md |
| 24 | +└── packages/ |
| 25 | + └── ui/ |
| 26 | + └── .specify/ # Spec Kit project "ui" |
| 27 | +``` |
| 28 | + |
| 29 | +Initialize each member project independently: |
| 30 | + |
| 31 | +```bash |
| 32 | +specify init apps/web --integration claude |
| 33 | +specify init apps/api --integration claude |
| 34 | +``` |
| 35 | + |
| 36 | +Each project keeps its own `specs/` directory and numbers features |
| 37 | +independently (`apps/web/specs/001-…`, `apps/api/specs/001-…`). |
| 38 | + |
| 39 | +## Working inside a member project |
| 40 | + |
| 41 | +The default workflow is unchanged: change into the project directory and run the |
| 42 | +slash commands. Root resolution finds the nearest `.specify/`. |
| 43 | + |
| 44 | +```bash |
| 45 | +cd apps/web |
| 46 | +# then run /speckit.specify, /speckit.plan, … in your agent |
| 47 | +``` |
| 48 | + |
| 49 | +## Targeting a member project from the repo root |
| 50 | + |
| 51 | +For non-interactive or CI runs where you do not want to `cd`, set |
| 52 | +**`SPECIFY_INIT_DIR`** to the member project root (the directory *containing* |
| 53 | +`.specify/`). Relative paths resolve against the current directory. |
| 54 | + |
| 55 | +```bash |
| 56 | +# operate on apps/web from the monorepo root (no cd required) |
| 57 | +export SPECIFY_INIT_DIR=apps/web |
| 58 | +``` |
| 59 | + |
| 60 | +The path must exist and contain `.specify/`. If it does not, the command |
| 61 | +**errors and does not fall back** to the current directory or the Git toplevel. |
| 62 | +This is deliberate: a typo never writes specs into the wrong project. A |
| 63 | +nonexistent path is reported as you typed it; a path that exists but is not a |
| 64 | +Spec Kit project is reported as its resolved absolute path: |
| 65 | + |
| 66 | +```text |
| 67 | +# SPECIFY_INIT_DIR=apps/wbe (typo: no such directory) |
| 68 | +ERROR: SPECIFY_INIT_DIR does not point to an existing directory: apps/wbe |
| 69 | +
|
| 70 | +# SPECIFY_INIT_DIR=apps (exists, but has no .specify/ of its own) |
| 71 | +ERROR: SPECIFY_INIT_DIR is not a Spec Kit project (no .specify/ directory): /home/you/my-monorepo/apps |
| 72 | +``` |
| 73 | + |
| 74 | +`SPECIFY_INIT_DIR` selects the **project**; `SPECIFY_FEATURE_DIRECTORY` selects |
| 75 | +the **feature** within it. They compose: set both to pick a project and a |
| 76 | +feature non-interactively. See the |
| 77 | +[`SPECIFY_INIT_DIR` reference](../reference/core.md#environment-variables) for |
| 78 | +the full contract and the two-axes model. |
| 79 | + |
| 80 | +## How `SPECIFY_INIT_DIR` reaches your agent |
| 81 | + |
| 82 | +`SPECIFY_INIT_DIR` is read by the shell scripts that the slash commands invoke |
| 83 | +(`get_repo_root` in Bash, `Get-RepoRoot` in PowerShell). It takes effect only |
| 84 | +when it is present in the environment of the shell that runs those scripts. |
| 85 | + |
| 86 | +- **Scripted / CI runs:** export it in the same shell that drives the commands; |
| 87 | + it is reliable there. |
| 88 | +- **Interactive agents:** whether an exported variable reaches the shell tool an |
| 89 | + agent uses is agent-specific. Export `SPECIFY_INIT_DIR` *before* launching the |
| 90 | + agent, and verify once (e.g. run `/speckit.specify` and confirm the new feature |
| 91 | + landed under the intended project's `specs/`). |
| 92 | + |
| 93 | +## Git in a monorepo |
| 94 | + |
| 95 | +> [!NOTE] |
| 96 | +> Spec Kit project files are scoped to the **resolved project root**, but Git |
| 97 | +> operations still run in the containing Git work tree. In a monorepo with a |
| 98 | +> single Git repository at the root and projects in subdirectories, feature |
| 99 | +> branch creation creates or switches branches in the shared root repository. |
| 100 | +> Spec directories still live under the selected member project, while the Git |
| 101 | +> branch namespace is shared by the whole monorepo. Manage branches and commits |
| 102 | +> at the repository root, or initialize Git per member project if you want |
| 103 | +> isolated per-project branch namespaces. |
| 104 | +
|
| 105 | +## Constitutions |
| 106 | + |
| 107 | +Each member project has its own `.specify/memory/constitution.md` and |
| 108 | +`/speckit.constitution` edits the local project's file. Spec Kit does not provide |
| 109 | +a built-in base/inheritance mechanism; if you want one constitution to reference |
| 110 | +shared rules elsewhere in the monorepo, you need to maintain that wiring yourself. |
| 111 | +Otherwise, duplicate or sync shared engineering rules per project. |
0 commit comments