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.

[PascalThuet]

Thanks !

I opened PR #2892 with the scoped version you suggested:

• env var first: SPECIFY_INIT_DIR
• points to the project root, i.e. the directory containing .specify/
• strict validation: invalid path or missing .specify/ fails fast
• no silent fallback to cwd or the git toplevel
• no --project flag in this PR

The PR updates the Bash and PowerShell common resolvers, wires the override into the bundled git and agent-context extension scripts, documents the behavior, and adds tests for valid targets, invalid targets, relative paths, unset behavior, and legacy-core extension fallback.

I kept branch namespacing, workspace manifests, constitution inheritance, and broader agent UX out of scope. This PR only adds a clear script-level project selector for non-interactive / CI use.

PR: #2892

[PascalThuet]

Now that SPECIFY_INIT_DIR has shipped (#2892), I'd like to line up the follow-up.

The env var only reaches the shell layer today. get_repo_root / Get-RepoRoot honor it, but the Python CLI doesn't: integration, extension, and workflow all resolve the project through _require_specify_project(), which is Path.cwd() + a .specify/ check and never reads SPECIFY_INIT_DIR. So setup-plan.sh respects it while specify integration install ignores it — you still have to cd into the sub-project.

I'd close that two ways, and I'm happy to do both in one PR if you want:

1. Have _require_specify_project() honor SPECIFY_INIT_DIR with the same strict contract as the shell resolver (relative to cwd, must exist and contain .specify/, hard error, no fallback). One resolver change plus the two commands that read cwd directly (integration scaffold, workflow run on a file path).
2. Add a --project <path> flag over the same resolution, precedence flag > env > cwd. (init doesn't need it — it already takes a target path and creates .specify/.)

If that works for you I'll open the PR with tests mirroring the strict cases in test_init_dir.py and a docs note on core.md. Which scope do you prefer — env var only, or env var + --project?

[mnriem]

For this particular one I say go ahead, but in principle we should NOT assume that any environment variable that is available when running a command will be made available in the CLI. I wanted to clarify this so it is clear that this is the exception and not the rule going forward