Mono repo considerations and best practices

[foundryserver]

Hello,

I use a mono repo for my organization. So each app/website/api is a folder in the mono repo. The big picture is that they all use the same db structure as the glue that bind them together. However each app/api has a specific job to do. For example, kubernetes provisioning a work load, or sending an email.

I am wondering how do I use spec kit in this situation? Is there one spec for the whole repo or can there be a spec in each dir for each micro service. Here is the dir structure

repo
- main website
- kubernetes api
- email api
- stripe api
- admin website
- proxmox api

I hope this question makes sense. I tried separate repo's for each micro service and it was just too cumbersome when making global changes. I am the only dev so it seems to work for me.

The project is fantastic btw.

Brad

[outp1]

I was thinking about this too. There is no native support for different project structures, but you can either:

• Init spec-kit in each subproject, which will involve you more in the feature design process. Less "vibecoding" approach, and more predictable outcomes for large monorepos.
• Init it in the root folder, which also works fine. With this approach, your agent will be able to work on a broader-scope features.

Regrettably, the first choice forces you to code within the subproject's working directory.

[yeuem1vannam]

In my case, we use a monorepo-within-monorepo structure because each sub-monorepo has a different tech stack. Ex:

• repo
  • platform: web-based tech stack; nextjs
    • apps/web
    • apps/admin
  • functions: lambda functions for tasks; python
    • throttle-login
    • backup

Each sub-monorepo comes with its own container setup. To support this, we use a spec-kit in each sub-monorepo and make small adjustments in the common.sh script, for example: platform/.specify/scripts/bash/common.sh

# Get repository root, with fallback for non-git repositories
get_repo_root() {
+    # This repo was configured in non-git mode, so we need to use the script location
+    # if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    #     git rev-parse --show-toplevel)
+    # else
        # Fall back to script location for non-git repos
        local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
        (cd "$script_dir/../../.." && pwd)
+    # fi
}

This setup works well for us, so I think get_repo_root should prioritize the --no-git config over git rev-parse.

[schnee]

I just had a situation in a mono-repo:

repo-root
└── project-root
    ├── .specify

initially after running /specify, the specs directory was inserted into repo-root. I moved it to project-root. I'm hoping this doesn't mess things up.

Should specs be parallel to where ever the .specify directory is (in general)? That way, the specifications are tied to the memory.

[outp1]

initially after running /specify, the specs directory was inserted into repo-root. I moved it to project-root. I'm hoping this doesn't mess things up.
It should not

Should specs be parallel to where ever the .specify directory is (in general)? That way, the specifications are tied to the memory.
They should be placed in the same dir.

@schnee, you have initialized the spec-kit in the subproject directory. Now, you need to set it as the current working directory.

[schnee]

@outp1 thank you.

When I initialized spec-kit, it was something like:

cd repo-root
mkdir project-root && cd project-root &&  uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai opencode --script sh

that apparently did not set the subproject directory (project-root) as the current working directory (which in this case should be project-root because of the --here correct?). How do I set spec-kit's current working directory? I doesn't seem to be a "cd" command.

[foundryserver]

Would the idea then to be, init the spec kit in the repo root. Then use spec kit to describe the project as a whole. Going through and defining what each application does and how they relate to one and other. Then when I want to work an app to add a feature, I could then do "/spec" making sure I refer to the correct app within the mono repo?

[ojalberts-itc]

Experiencing similar frustration with location of the spec folder in the REPO_ROOT in a mono repo, working with worktrees almost exclusively. In my mind this should be located int the PROJECT_ROOT or WORKSPACE_ROOT? Especially for worktrees this would be preferred in our case.
Having the specs folder in the REPO_ROOT causes confusion and does not support separation of concerns. The simplest solution might be to just allow the user to specify the root and record it in Spec Kit's memory for future use? Although that might complicated the scripts.
For now, i have edited the scripts to look in the workspace root instead of REPO_ROOT. This works, but is far from an ideal long term fix. I subsequently rolled these changes back to avoid future headaches.
Keep in mind that mono repos by their mere existence and definition means hosting multiple project "repos" in one git repo. The physical limitation of git's "limited" support for sub-repos made this a necessity.

[schnee]

I have found that I can "force" the behavior I want with commands such as:

/tasks specs/001-feature/plan.md

that is, being very explicit with the pathing (the above assumes I'm in PROJECT_ROOT).

Thinking about mono-repos, one could envision a future where a repo-level constitution.md exists, as well as project-level constitutions. Spec-kit could assemble them as it processes, allowing for a cascade of governance.

[mlaass]

I did this

get_repo_root() {
+    # This repo was configured in non-git mode, so we need to use the script location
+    # if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    #     git rev-parse --show-toplevel)
+    # else
        # Fall back to script location for non-git repos
        local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
        (cd "$script_dir/../../.." && pwd)
+    # fi
}

and search replaced "repo root" with "project root" in the commands, so far seems to do the trick

[ojalberts-itc]

I did this

get_repo_root() {
+    # This repo was configured in non-git mode, so we need to use the script location
+    # if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    #     git rev-parse --show-toplevel)
+    # else
        # Fall back to script location for non-git repos
        local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
        (cd "$script_dir/../../.." && pwd)
+    # fi
}

and search replaced "repo root" with "project root" in the commands, so far seems to do the trick

I did this too. The problem with this is that if you apply any updates from spec-kit to your repo/project then the scripts will be overwritten and you lose the change. So not ideal, but it works.

[fabiodouek]

Same here, the workaround worked partially and it was trying to inspect the code in the root dir.

Ideally whenever initializing in a subdir, the tool should bootstrap the script automatically to handle specifying a base directory

[voroshkov]

Strongly vote for changing all scripts to use project root instead of monorepo root as well.

[aurexav]

Please support this. It becomes more and more important for managing big project with AI.

---

My temporary fix is:

mv .git .git.bak
specify init --no-git --ai codex --script sh mono-repo-sub-project
cd mono-repo-sub-project
CODEX_HOME=.codex codex
# run /specify.cmds
# exit codex
cd ..
mv .git.bak .git