feat: Plan-aware nested repo branching for multi-module workspaces

[sakitA]

Summary

Adds support for nested independent git repositories in multi-module workspaces. Sub-components that live under the root workspace with their own .git but are not formal git submodules.

Instead of automatically branching all nested repos during feature creation, this PR implements a plan-aware, task-driven workflow where the AI agent identifies affected repos from the spec and generates targeted branch-creation tasks.

Resolves #2120

Problem

In multi-module projects where sub-components maintain independent git histories (nested under a shared root), spec-kit only operates on the root repo. Developers must manually create matching feature branches in each affected sub-component.

Workflow

Phase	What Happens
Specify	Creates root branch + spec only
Plan	setup-plan.sh/.ps1 discovers nested repos (NESTED_REPOS in JSON). AI identifies affected repos from spec
Tasks	Generates Phase 1 setup task for branching only the affected nested repos
Implement	Executes the branch-creation task via git commands

Design Decisions

• Discovery in plan phase, not specify: At specify time the spec does not exist yet
• AI-driven selection: AI agent determines affected repos by analyzing spec against discovered repos
• Configurable depth: --scan-depth N / -ScanDepth N controls scan depth (default: 2)
• Non-blocking: Discovery failures produce warnings, do not abort
• Backward-compatible: Single-repo projects see zero behavior change

Changes

File	Change
scripts/bash/common.sh	ind_nested_git_repos() recursive discovery in subshell
scripts/bash/setup-plan.sh	--scan-depth flag with validation, NESTED_REPOS in JSON
scripts/powershell/common.ps1	Find-NestedGitRepos with -MaxDepth param
scripts/powershell/setup-plan.ps1	-ScanDepth param, NESTED_REPOS in JSON
emplates/commands/plan.md	Step 3: AI identifies affected repos from spec
emplates/plan-template.md	Affected Nested Repositories section
emplates/commands/tasks.md	Guidance for branch-creation setup task
emplates/tasks-template.md	Phase 1 example for nested repo branching
emplates/commands/specify.md	Note pointing to plan+tasks
ests/test_nested_repos.py	13 tests covering full workflow

Testing

• 13 new tests, all passing
• Covers: discovery, configurable depth, setup-plan JSON output, verify specify does NOT branch

AI Disclosure

This contribution was made with AI assistance (GitHub Copilot), as required by CONTRIBUTING.md.

[Copilot]

Pull request overview

Adds coordinated feature-branch creation for workspaces that contain nested, independent git repositories (not formal submodules), so create-new-feature can create/switch the same feature branch across the root repo and detected nested repos and report results in JSON.

Changes:

• Add nested repo discovery helpers (find_nested_git_repos / Find-NestedGitRepos) scanning up to 2 levels deep with a skip list.
• Create/switch matching branches in detected nested repos from both Bash and PowerShell create-new-feature scripts, and emit NESTED_REPOS in JSON output.
• Document NESTED_REPOS and add pytest coverage for Bash discovery/branching behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
scripts/bash/common.sh	Adds nested git repo discovery helper for Bash.
scripts/bash/create-new-feature.sh	Creates matching branches in discovered nested repos and includes NESTED_REPOS in JSON output.
scripts/powershell/common.ps1	Adds nested git repo discovery helper for PowerShell.
scripts/powershell/create-new-feature.ps1	Creates matching branches in discovered nested repos and includes NESTED_REPOS in JSON output.
templates/commands/specify.md	Documents the new NESTED_REPOS JSON field and behavior.
tests/test_nested_repos.py	Adds tests for nested repo discovery + Bash branching + JSON output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In find_nested_git_repos, the helper _should_skip() is defined inside the function but becomes a global function in bash (functions aren't scoped). Because it relies on dynamically-scoped skip_dirs, calling it outside this function (or redefining it elsewhere) can lead to hard-to-debug behavior. Consider replacing this with a case/[[ ... ]] check inline, or use a uniquely-named helper and unset -f it before returning.

[Copilot]

find_nested_git_repos only scans “level 2” when the level-1 directory does not have a .git marker. That means a repo at $repo_root/child/.git will prevent discovery of another repo at $repo_root/child/grandchild/.git, even though it's still within 2 levels of the root. If the intent is truly “scan up to 2 levels deep”, the level-2 traversal should run regardless (while still applying the skip list).

Suggested change

	else
	# Level 2
	for grandchild in "$child"/*/; do
	[ -d "$grandchild" ] || continue
	grandchild="${grandchild%/}"
	local gc_name
	gc_name="$(basename "$grandchild")"
	_should_skip "$gc_name" && continue
	if [ -e "$grandchild/.git" ]; then
	if git -C "$grandchild" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
	echo "$grandchild"
	fi
	fi
	done
	fi
	fi
	# Level 2
	for grandchild in "$child"/*/; do
	[ -d "$grandchild" ] || continue
	grandchild="${grandchild%/}"
	local gc_name
	gc_name="$(basename "$grandchild")"
	_should_skip "$gc_name" && continue
	if [ -e "$grandchild/.git" ]; then
	if git -C "$grandchild" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
	echo "$grandchild"
	fi
	fi
	done

[Copilot]

rel_path="${nested_path#"$REPO_ROOT/"}" uses bash pattern matching in parameter expansion, so repo roots containing glob characters (e.g. [ or *) can produce incorrect stripping and leak absolute paths into NESTED_REPOS.path. A safer approach is to compute the relative path by string length (only after verifying the prefix), or delegate to a tool like python/realpath for literal path handling.

Suggested change

	while IFS= read -r nested_path; do
	[ -z "$nested_path" ] && continue
	# Normalize: remove trailing slash
	nested_path="${nested_path%/}"
	# Compute relative path for output
	rel_path="${nested_path#"$REPO_ROOT/"}"
	repo_root_prefix="${REPO_ROOT%/}/"
	while IFS= read -r nested_path; do
	[ -z "$nested_path" ] && continue
	# Normalize: remove trailing slash
	nested_path="${nested_path%/}"
	# Compute relative path for output using literal prefix handling
	if [ "${nested_path:0:${#repo_root_prefix}}" = "$repo_root_prefix" ]; then
	rel_path="${nested_path:${#repo_root_prefix}}"
	else
	rel_path="$nested_path"
	fi

[Copilot]

Find-NestedGitRepos only descends to the second directory level when the level-1 directory does not contain a .git marker. This skips repos that are still within 2 levels of $RepoRoot but happen to be nested under a level-1 repo. If the intended behavior is “scan up to 2 levels deep”, consider always scanning grandchildren (while still excluding .git / other skip dirs).

Suggested change

	} else {
	# Level 2
	$grandchildren = Get-ChildItem -Path $child.FullName -Directory -ErrorAction SilentlyContinue |
	Where-Object { $skipDirs -notcontains $_.Name }
	foreach ($gc in $grandchildren) {
	$gcGitMarker = Join-Path $gc.FullName '.git'
	if (Test-Path -LiteralPath $gcGitMarker) {
	try {
	$null = git -C $gc.FullName rev-parse --is-inside-work-tree 2>$null
	if ($LASTEXITCODE -eq 0) {
	$results += $gc.FullName
	}
	} catch { }
	}
	}
	# Level 2
	$grandchildren = Get-ChildItem -Path $child.FullName -Directory -ErrorAction SilentlyContinue |
	Where-Object { $skipDirs -notcontains $_.Name }
	foreach ($gc in $grandchildren) {
	$gcGitMarker = Join-Path $gc.FullName '.git'
	if (Test-Path -LiteralPath $gcGitMarker) {
	try {
	$null = git -C $gc.FullName rev-parse --is-inside-work-tree 2>$null
	if ($LASTEXITCODE -eq 0) {
	$results += $gc.FullName
	}
	} catch { }

[Copilot]

$relPath = $nestedPath.Substring($repoRoot.Length).TrimStart(...) assumes $nestedPath always starts with the exact $repoRoot string (same casing, no trailing separator differences). Using [System.IO.Path]::GetRelativePath($repoRoot, $nestedPath) (or Resolve-Path normalization + a safer relative-path helper) would avoid subtle path mismatches and make output paths more reliable across platforms/filesystems.

Suggested change

	$relPath = $nestedPath.Substring($repoRoot.Length).TrimStart('\', '/')
	$relPath = [System.IO.Path]::GetRelativePath($repoRoot, $nestedPath)

[Copilot]

This test module’s header says it covers PowerShell discovery (Find-NestedGitRepos) and “graceful handling when nested repos cannot be branched”, but there are currently no tests exercising the PowerShell scripts or a nested-branch failure scenario (e.g., dirty worktree causing checkout to fail). Either add those cases (similar to tests/test_timestamp_branches.py’s conditional pwsh runner), or adjust the docstring/scope so it matches what’s actually being validated.

Suggested change

	Pytest tests for nested independent git repository support in create-new-feature scripts.
	Tests cover:
	- Discovery of nested git repos via find_nested_git_repos (bash) / Find-NestedGitRepos (PS)
	- Branch creation in nested repos during feature creation
	- JSON output includes NESTED_REPOS field
	- --dry-run reports nested repos without creating branches
	- --allow-existing-branch propagates to nested repos
	- Excluded directories are skipped
	- Graceful handling when nested repos cannot be branched
	Pytest tests for nested independent git repository support in the Bash
	create-new-feature script.
	Tests cover:
	- Discovery of nested git repos via find_nested_git_repos (bash)
	- Branch creation in nested repos during feature creation
	- JSON output includes NESTED_REPOS field
	- --dry-run reports nested repos without creating branches
	- --allow-existing-branch propagates to nested repos
	- Excluded directories are skipped

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

templates/commands/plan.md:88

• Outline numbering is inconsistent: there are two items numbered 5. (Stop and report, then Check for extension hooks). This can confuse agents/instructions parsing; please renumber the second one to 6. (and ensure subsequent numbering remains consistent).

   - Phase 1: Generate data-model.md, contracts/, quickstart.md
   - Phase 1: Update agent context by running the agent script
   - Re-evaluate Constitution Check post-design

5. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, generated artifacts, and affected nested repos (if any).

5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
   - If it exists, read it and look for entries under the `hooks.after_plan` key
   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PR description/title says create-new-feature now creates matching branches in nested repos and reports NESTED_REPOS, but this note explicitly states nested repo branching is not handled in specify (create-new-feature) and is deferred to plan/tasks. Please reconcile the implementation + docs/tests with the PR description (either implement branching in create-new-feature + add NESTED_REPOS there, or update the PR description/title to match the new workflow).

[Copilot]

These tests assert that create-new-feature.sh does not branch nested repos and that its JSON output omits NESTED_REPOS, which directly contradicts the PR description stating create-new-feature now coordinates branching across nested repos and reports NESTED_REPOS. Either the feature implementation is missing from create-new-feature, or the PR description/tests need to be updated to match the intended behavior.

[Copilot]

find_nested_git_repos defines helper functions (_should_skip, _scan_dir) inside the function body. In bash this still creates global function names, which can unintentionally pollute/override other helpers in common.sh and makes the namespace harder to maintain. Consider inlining this logic, using more uniquely prefixed helper names (e.g. __find_nested_git_repos_*), or running the scan in a subshell to avoid exporting generic helper names globally.

Suggested change

	_should_skip() {
	local name="$1"
	for skip in "${skip_dirs[@]}"; do
	[ "$name" = "$skip" ] && return 0
	done
	return 1
	}
	_scan_dir() {
	local dir="$1"
	local current_depth="$2"
	for child in "$dir"/*/; do
	[ -d "$child" ] || continue
	child="${child%/}"
	local child_name
	child_name="$(basename "$child")"
	_should_skip "$child_name" && continue
	if [ -e "$child/.git" ]; then
	if git -C "$child" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
	echo "$child"
	fi
	elif [ "$current_depth" -lt "$max_depth" ]; then
	_scan_dir "$child" $((current_depth + 1))
	fi
	done
	}
	_scan_dir "$repo_root" 1
	(
	_should_skip() {
	local name="$1"
	local skip
	for skip in "${skip_dirs[@]}"; do
	[ "$name" = "$skip" ] && return 0
	done
	return 1
	}
	_scan_dir() {
	local dir="$1"
	local current_depth="$2"
	local child
	local child_name
	for child in "$dir"/*/; do
	[ -d "$child" ] || continue
	child="${child%/}"
	child_name="$(basename "$child")"
	_should_skip "$child_name" && continue
	if [ -e "$child/.git" ]; then
	if git -C "$child" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
	echo "$child"
	fi
	elif [ "$current_depth" -lt "$max_depth" ]; then
	_scan_dir "$child" $((current_depth + 1))
	fi
	done
	}
	_scan_dir "$repo_root" 1
	)

[Copilot]

--scan-depth is accepted as an arbitrary string and is passed through to find_nested_git_repos, which later uses -lt numeric comparisons. If the value is missing or non-numeric (e.g. --scan-depth --json), this can produce integer expression expected errors and unexpected scan behavior. Consider validating that SCAN_DEPTH is a positive integer when parsing args and exiting with a clear error if it isn't.

Suggested change

	# Reset sentinel if --scan-depth was passed without a value
	[ "$SCAN_DEPTH" = "__NEXT__" ] && SCAN_DEPTH=""
	# Validate --scan-depth argument if provided
	if [ "$SCAN_DEPTH" = "__NEXT__" ]; then
	echo "ERROR: --scan-depth requires a positive integer value" >&2
	exit 1
	fi
	if [ -n "$SCAN_DEPTH" ]; then
	case "$SCAN_DEPTH" in
	''|*[!0-9]*|0)
	echo "ERROR: --scan-depth must be a positive integer" >&2
	exit 1
	;;
	esac
	fi

[Copilot]

This template instructs the agent to read .specify/init-options.json for nested_repo_scan_depth, but that key doesn't appear to be written/used anywhere else in the repo. Either add support for persisting this option (and document it), or remove/adjust this instruction so agents don’t look for a config value that will never exist.

Suggested change

**Nested repo scan depth**: Check `.specify/init-options.json` for `nested_repo_scan_depth`. If present, pass `--scan-depth N` (Bash) or `-ScanDepth N` (PowerShell) to the script.

[Copilot]

The generated setup task command should quote <repo_path> (and ideally <BRANCH_NAME>) to handle paths with spaces and avoid shell parsing issues. Consider specifying git -C "<repo_path>" checkout -b "<BRANCH_NAME>" (or equivalent) in this instruction text.

Suggested change

	- If plan.md contains an "Affected Nested Repositories" section: extract the repo paths and reasons. Generate a setup task (in Phase 1) to create the feature branch in each affected nested repo using `git -C <repo_path> checkout -b <BRANCH_NAME>`. The branch name comes from the current feature branch.
	- If plan.md contains an "Affected Nested Repositories" section: extract the repo paths and reasons. Generate a setup task (in Phase 1) to create the feature branch in each affected nested repo using `git -C "<repo_path>" checkout -b "<BRANCH_NAME>"`. The branch name comes from the current feature branch.

[Copilot]

The comment above Find-NestedGitRepos says it "Searches up to 2 directory levels deep", but the implementation accepts a configurable -MaxDepth parameter. Please update the comment to reflect that scan depth is configurable (default 2) so the documentation matches behavior.

[mnriem]

Please deliver this as a community preset. See https://github.com/github/spec-kit/tree/main/presets