Targeting a member project from the monorepo root

[PascalThuet]

AI-assistance disclosure: drafted with help from an AI coding agent,
human-reviewed before posting.

I may be missing an existing workflow here, but this is the concrete gap I hit.

Given a monorepo like this:

repo/
  apps/web/.specify/
  apps/api/.specify/

Spec Kit works if I first move into the project:

cd apps/web

From there, #1933 means specs, plans, and numbering stay under apps/web.

What I do not see is a way to stay at repo/ and say:

run this Spec Kit command against apps/web

That is what I am proposing: a way to choose the project by path.

Possible forms:

• SPECIFY_PROJECT=apps/web
• --project apps/web

Expected behavior:

• if the target is apps/web, Spec Kit treats apps/web/.specify as the project;
• files are written under apps/web/specs, not repo/specs;
• feature numbering uses the target project;
• if no target is provided, current behavior stays unchanged.

I would avoid the name SPECIFY_ROOT; in a monorepo, "root" can mean git root, workspace root, or Spec Kit project root.

This seems related to #1026. It may not solve every agent's slash-command discovery by itself, but it would give the CLI/scripts/integrations one clear project selector to build on.

Not trying to solve these in this thread:

• branch namespacing ([Feature request] Custom namespacing and branch naming conventions #1382);
• parent-git logging in nested layouts;
• constitution inheritance / base+override composition;
• workspace manifests or automatic downward discovery.

Question: is a project path option acceptable for Spec Kit? If yes, should it be env only, CLI flag only, or both?

[mnriem]

I am not sure this should be the responsibility of the CLI to be honest. Your specification can clearly spell out that you are working on a given directory?

[PascalThuet]

Fair point. You're right that cd apps/web works. The agent or a person can do it, and everything resolves from there. I'm not saying that's broken.

The gap is non-interactive use. common.sh finds the project by walking up from the current directory to a .specify folder. specs/, feature numbering, and template lookup all derive from that. Nothing reads the spec content, so the only way to pick a project is to be inside it.

That's fine in a terminal. It's fragile for a script or CI step running from the repo root, where a manual cd per command is easy to get wrong. A --project / SPECIFY_PROJECT option would let a command run against a given path without changing directory first, the same way git -C does.

Would you be open to that for the non-interactive case?

[mnriem]

Thanks for the detailed write-up, and for cleanly separating this from the harder questions (branch namespacing, constitution inheritance, workspace manifests).

I think there's a real, narrowly-scoped gap here that's worth filling. Today the resolver in scripts/bash/common.sh is anchored on $(pwd) via find_specify_root, and the existing env-var overrides (SPECIFY_FEATURE, SPECIFY_FEATURE_DIRECTORY) are scoped narrower than the project. There's no input mechanism that says "treat this path as the project," which is exactly the non-interactive / CI case you describe.

If we do this, I'd suggest:

• Env var first, name it SPECIFY_INIT_DIR. It has a concrete referent (specify init is the command that creates the directory), avoids the "root vs project root vs git root" ambiguity you flagged, and pairs naturally with the existing SPECIFY_FEATURE / SPECIFY_FEATURE_DIRECTORY overrides. It points at the project root (the directory containing .specify/), not .specify/ itself.
• Strict validation, no silent fallback. If SPECIFY_INIT_DIR is set, the path must resolve to a directory containing .specify/. Hard error otherwise — never fall back to cwd or git root, since that would silently write to the wrong project's specs/.
• Defer the CLI flag. A --project flag on specify itself is reasonable for init / integration subcommands, but adding it to per-script slash commands would mean updating every template's invocation string. The env var covers the CI/non-interactive case without that surface change.
• One nuance worth naming: a few agent integrations spawn scripts in fresh shells, so env-var propagation will need a quick audit per integration. Not a blocker, but worth knowing up front.

Scoped this way, the change is small: wire the env var into find_specify_root call sites in scripts/bash/common.sh, mirror in scripts/powershell/common.ps1, and document precedence vs. SPECIFY_FEATURE_DIRECTORY (project-then-feature).

Tests should cover both sides of the contract:

• Positive: SPECIFY_INIT_DIR set to a valid project path resolves correctly from outside that directory; relative paths are normalized against cwd; trailing slashes are tolerated; precedence over branch-prefix and feature.json lookups behaves as documented.
• Negative: unset variable preserves today's $(pwd)-walking behavior; a path that doesn't exist errors clearly; a path that exists but doesn't contain .specify/ errors clearly (no silent fallback to git root or cwd); an empty string is treated as unset rather than as ".".

Happy to review a PR along those lines.