Problem
When working with multi-module projects where sub-components have their own independent git repositories nested under a parent project directory, spec-kit's create-new-feature.sh / create-new-feature.ps1 only creates the feature branch on the root repository (where .specify/ is initialized). The nested repositories remain on their previous branch (e.g., main), creating a workflow mismatch.
Project Structure Example
my-project/ root git repo (.specify/ lives here)
.specify/
.git/
components/
core/ independent git repo (.git/)
api/ independent git repo (.git/)
shared-lib/ independent git repo (.git/)
build.gradle
specs/
Each component under components/ has its own .git directory and is an independent repository. They are not git submodules they are simply co-located independent repos within the parent directory structure. This is a common pattern in enterprise multi-module projects to avoid the complexity and overhead of git submodules (e.g., polluting the parent repo with submodule pointer updates on every commit).
Current Behavior
- Running
/speckit.specify triggers create-new-feature.sh
- The script calls
git checkout -b "003-my-feature" this only affects the root repository
- Nested repos (
components/core/, components/api/, etc.) remain on main or whatever branch they were on
- When implementing the feature across modules, changes in nested repos are on mismatched branches
- This makes it difficult to coordinate PRs, track feature work across modules, and maintain clean branch-per-feature workflows
Desired Behavior
When create-new-feature.sh (or .ps1) creates a feature branch:
- Create the feature branch on the root repository (current behavior unchanged)
- Auto-detect nested independent git repositories within the workspace (directories containing
.git that are not the root)
- Create the same feature branch in each detected nested repository
- Report the results (which repos were branched) in the JSON output, e.g.:
{
"BRANCH_NAME": "003-my-feature",
"SPEC_FILE": "/path/to/specs/003-my-feature/spec.md",
"FEATURE_NUM": "003",
"NESTED_REPOS": [
{"path": "components/core", "status": "created"},
{"path": "components/api", "status": "created"},
{"path": "components/shared-lib", "status": "created"}
]
}
- Warn but don't fail if a nested repo can't be branched (e.g., has uncommitted changes)
- Support
--dry-run to preview which nested repos would be affected
Scope
- Both
scripts/bash/create-new-feature.sh and scripts/powershell/create-new-feature.ps1
- Auto-detection of nested
.git directories (1-2 levels deep from root)
- Exclusion of common non-project directories (
node_modules/, .specify/, vendor/, etc.)
--allow-existing-branch should propagate to nested repos
- Backward-compatible: single-repo projects see no behavior change
Related Issues
Use Cases
- Enterprise frameworks with modular architecture where each module is an independent repo
- Monorepo-adjacent setups where teams want module isolation without submodule overhead
- Any multi-module project using co-located independent repos under a shared parent directory
Problem
When working with multi-module projects where sub-components have their own independent git repositories nested under a parent project directory, spec-kit's
create-new-feature.sh/create-new-feature.ps1only creates the feature branch on the root repository (where.specify/is initialized). The nested repositories remain on their previous branch (e.g.,main), creating a workflow mismatch.Project Structure Example
Each component under
components/has its own.gitdirectory and is an independent repository. They are not git submodules they are simply co-located independent repos within the parent directory structure. This is a common pattern in enterprise multi-module projects to avoid the complexity and overhead of git submodules (e.g., polluting the parent repo with submodule pointer updates on every commit).Current Behavior
/speckit.specifytriggerscreate-new-feature.shgit checkout -b "003-my-feature"this only affects the root repositorycomponents/core/,components/api/, etc.) remain onmainor whatever branch they were onDesired Behavior
When
create-new-feature.sh(or.ps1) creates a feature branch:.gitthat are not the root){ "BRANCH_NAME": "003-my-feature", "SPEC_FILE": "/path/to/specs/003-my-feature/spec.md", "FEATURE_NUM": "003", "NESTED_REPOS": [ {"path": "components/core", "status": "created"}, {"path": "components/api", "status": "created"}, {"path": "components/shared-lib", "status": "created"} ] }--dry-runto preview which nested repos would be affectedScope
scripts/bash/create-new-feature.shandscripts/powershell/create-new-feature.ps1.gitdirectories (1-2 levels deep from root)node_modules/,.specify/,vendor/, etc.)--allow-existing-branchshould propagate to nested reposRelated Issues
.gitmodules, no submodule references). Both share the same root cause: spec-kit assumes a single git repository per workspace.Use Cases