Support namespaced git feature branch templates

[PascalThuet]

Summary

• Adds git extension branch_template config with {author}, {app}, {number}, and {slug} tokens, plus branch_prefix as a shorthand namespace.
• Applies templates in both Bash and PowerShell feature-branch scripts while preserving the default {number}-{slug} branch shape.
• Makes feature number extraction, branch-number scanning, and validation tolerant of path-style branch namespaces without confusing numeric namespace segments for feature numbers.

Why

Monorepo installs can have separate Spec Kit projects but one shared root Git branch namespace. This lets projects opt into names like jdoe/app-a/008-guided-tour without requiring separate Git repositories or changing downstream feature path resolution.

Fixes #3081.

Issue context

The implementation follows the concrete monorepo use case described in #3081 (comment). That comment is relevant because it identifies the target branch shape ({author}/{app}/{number}-{slug}) and points out that downstream commands already resolve feature directories through .specify/feature.json / SPECIFY_FEATURE_DIRECTORY, so branch creation and validation are the important places to make namespace-aware.

TDD sequence

• dbe9203 adds failing coverage for branch templates, branch-prefix shorthand, namespace-scoped numbering, namespaced GIT_BRANCH_NAME extraction, and nested-prefix validation.
• f48178d implements the first pass that makes those tests pass.
• ee0574b adds failing edge-case coverage for numeric namespace segments, templates missing {number}, namespaced GIT_BRANCH_NAME, and validation false positives.
• 7a2a8b2 hardens parsing/validation and updates config discoverability so those edge cases pass.
• 8c5f2d7 addresses Copilot review feedback and the follow-up local review findings: branch_prefix help text, GIT_BRANCH_NAME fallback behavior, final-segment template validation, validation docs, config comments, and Bash UTF-8 byte reporting.

Validation

• Red check after dbe9203: 5 targeted tests failed as expected.
• Red check after ee0574b: 4 targeted tests failed as expected.
• Red check before 8c5f2d7: 4 targeted Bash tests failed as expected.
• Green check after 8c5f2d7: .venv/bin/python -m pytest tests/extensions/git/test_git_extension.py tests/test_timestamp_branches.py -q
• Result: 113 passed, 50 skipped.
• Additional local checks after 8c5f2d7: bash -n extensions/git/scripts/bash/create-new-feature-branch.sh extensions/git/scripts/bash/git-common.sh, git diff --check origin/main...HEAD, and uvx ruff check tests/extensions/git/test_git_extension.py.

Disclosure

Prepared on behalf of @PascalThuet by Codex (model: GPT-5, autonomous). Each commit includes an Assisted-by: trailer.

[mnriem]

I realize this still a draft, but I wanted to make sure that you should merge the template into the git-config.yml for ease of use

[PascalThuet]

Thanks, done in the latest push. branch_template is now included in both git-config.yml and config-template.yml.

It defaults to "", which preserves the existing {number}-{slug} behavior. Users can set it to {author}/{app}/{number}-{slug} for monorepo-style branch names.

[PascalThuet]

Posted on behalf of @PascalThuet by Codex (model: GPT-5, autonomous).

Updated the draft PR after a local code review pass:

• Added edge-case tests in ee0574b for numeric namespace segments, templates missing {number}, namespaced GIT_BRANCH_NAME, and validation false positives.
• Fixed those cases in 7a2a8b2 by extracting feature numbers from the feature segment instead of arbitrary numeric namespace segments, requiring {number} in custom templates, and making branch_prefix visible in the default config.
• Re-ran .venv/bin/python -m pytest tests/extensions/git/test_git_extension.py tests/test_timestamp_branches.py -q: 109 passed, 47 skipped.

[mnriem]

I triggered a Copilot review and a test & lint cycle so you can see where you are at from that perspective

[Copilot]

Pull request overview

Adds support for namespaced/templated feature-branch names in the Git extension so monorepo projects can share a single Git branch namespace while keeping per-project feature numbering intact.

Changes:

• Introduces branch_template and branch_prefix config options to render namespaced branch names (Bash + PowerShell).
• Updates branch-number scanning and feature-branch validation to treat the feature marker as the final path segment (after /).
• Adds/extends test coverage for templates, namespace-scoped numbering, and nested-prefix validation.

Show a summary per file

File	Description
tests/extensions/git/test_git_extension.py	Adds coverage for branch templates/prefixes, namespace-scoped numbering, and namespaced validation across Bash/PowerShell.
extensions/git/scripts/bash/create-new-feature-branch.sh	Applies branch_template / branch_prefix for branch rendering and namespace-scoped number scanning; adjusts truncation behavior.
extensions/git/scripts/powershell/create-new-feature-branch.ps1	PowerShell parity for template/prefix rendering, scoped numbering, and UTF-8 byte-limit truncation.
extensions/git/scripts/bash/git-common.sh	Updates feature-branch validation to accept path-style namespaces by validating only the final segment.
extensions/git/scripts/powershell/git-common.ps1	Mirrors Bash validation changes for namespaced branches (final-segment matching).
extensions/git/README.md	Documents new template/prefix configuration and intended monorepo branch shapes.
extensions/git/git-config.yml	Adds branch_template / branch_prefix to the extension’s default config.
extensions/git/config-template.yml	Adds template/prefix keys to the user-facing config template.
extensions/git/extension.yml	Updates extension metadata + default config values for new keys.
extensions/git/commands/speckit.git.feature.md	Documents template/prefix behavior and namespaced GIT_BRANCH_NAME extraction semantics.
extensions/git/commands/speckit.git.validate.md	Updates validation docs for namespaced feature markers.

Review details

Tip

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

Comments suppressed due to low confidence (1)

extensions/git/scripts/bash/create-new-feature-branch.sh:529

• These log lines label the counts as "bytes" but use Bash string length (${#...}), which is character-count under most locales and can be wrong for UTF-8. Since the limit check uses _byte_length, the reporting should too.

    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"

• Files reviewed: 11/11 changed files
• Comments generated: 4
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 3
• Review effort level: Low

[mnriem]

Please address Copilot feedback