Skip to content

Commit b6b74d4

Browse files
authored
docs: add monorepo guide (#3084)
* 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)
1 parent 0ef53eb commit b6b74d4

2 files changed

Lines changed: 113 additions & 0 deletions

File tree

‎docs/guides/monorepo.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
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.

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@
5353
href: local-development.md
5454
- name: Evolving Specs
5555
href: guides/evolving-specs.md
56+
- name: Monorepos
57+
href: guides/monorepo.md
5658

5759
# Community
5860
- name: Community

0 commit comments

Comments
 (0)