Skip to content

[Feature]: Support coordinated feature branching across nested independent git repositories #2120

@sakitA

Description

@sakitA

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

  1. Running /speckit.specify triggers create-new-feature.sh
  2. The script calls git checkout -b "003-my-feature" this only affects the root repository
  3. Nested repos (components/core/, components/api/, etc.) remain on main or whatever branch they were on
  4. When implementing the feature across modules, changes in nested repos are on mismatched branches
  5. 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:

  1. Create the feature branch on the root repository (current behavior unchanged)
  2. Auto-detect nested independent git repositories within the workspace (directories containing .git that are not the root)
  3. Create the same feature branch in each detected nested repository
  4. 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"}
      ]
    }
  5. Warn but don't fail if a nested repo can't be branched (e.g., has uncommitted changes)
  6. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions