docs: add monorepo guide#3084
Conversation
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 (github#3081), and per-project constitutions. Wires it into docs/toc.yml under Development.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Sorry I am going to reject this PR as it currently stands as we are not going to document open issues in our guides as it is too easy to forget to remove them and then the guidance is incorrect in perpetuity
|
Done. The Git note no longer references any issue. It documents current behavior only: in a monorepo with one root Git repository, feature branches are created in that shared root repo while spec directories stay under the selected member project. This is stable guidance with nothing that can go stale, which directly addresses the concern you raised. Would you accept the PR with this change? |
There was a problem hiding this comment.
Pull request overview
Adds a new documentation guide describing how to use Spec Kit in a monorepo, with emphasis on per-project .specify/ roots, using SPECIFY_INIT_DIR to target a member project from the repo root (as introduced in #2892), and how Git/constitutions behave in that setup.
Changes:
- Adds a new guide at
docs/guides/monorepo.mdcovering recommended monorepo layouts and workflows. - Documents
SPECIFY_INIT_DIRusage patterns (CI/non-interactive and interactive agent environments). - Wires the new guide into the documentation TOC under the Development section.
Show a summary per file
| File | Description |
|---|---|
| docs/toc.yml | Adds the new “Monorepos” entry under Development. |
| docs/guides/monorepo.md | New monorepo guide covering project root resolution, SPECIFY_INIT_DIR, Git behavior, and per-project constitutions. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 2/2 changed files
- Comments generated: 1
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback
|
|
||
| ## Constitutions | ||
|
|
||
| Each member project has its own `.specify/memory/constitution.md` and |
There was a problem hiding this comment.
While correct it is certainly possible for a constitution.md to refer to another constitution in another directory. But that plumbing is something one would have to do yourself
Adds a guide for using Spec Kit in a monorepo: per-project
.specify/, targeting amember project from the repo root with
SPECIFY_INIT_DIR(#2892), how the env varreaches the agent, how Git operations resolve in a monorepo, and per-project
constitutions.
Docs-only; documents already-merged behavior. New page
docs/guides/monorepo.md,wired into
docs/toc.ymlunder Development.(AI assistance: drafted and verified with an AI coding agent; reviewed by me.)