Customizable Branch Naming Templates

CHANGELOG.md

@@ -7,6 +7,38 @@ All notable changes to the Specify CLI and templates are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.24] - 2026-01-26
+
+### Fixed
+
+- **Branch Name Truncation**: Fixed truncation logic in `create-new-feature.sh` and `create-new-feature.ps1` to correctly guarantee GitHub's 244-byte branch name limit. The calculation now properly computes the maximum allowed length for the `{short_name}` segment based on the template overhead after resolving `{number}`.
+- **Interactive Settings Overwrite Prompt**: When `.specify/settings.toml` already exists and `--force` is not provided, the CLI now prompts with "Overwrite? [y/N]" instead of simply exiting. This aligns with standard CLI behavior for file overwrites.
+
+## [0.0.23] - 2026-01-23
+
+### Added
+
+- **Customizable Branch Naming Templates**: Teams can now configure branch naming patterns via `.specify/settings.toml`
+  - New `branch.template` setting supports placeholders: `{number}`, `{short_name}`, `{username}`, `{email_prefix}`
+  - Per-user number scoping: When using `{username}` prefix, each team member gets their own independent number sequence
+  - Automatic username resolution from Git config with OS username fallback
+  - Examples:
+    - `"{number}-{short_name}"` → `001-add-login` (default, solo developer)
+    - `"{username}/{number}-{short_name}"` → `johndoe/001-add-login` (team)
+    - `"feature/{username}/{number}-{short_name}"` → `feature/johndoe/001-add-login`
+  - Full backward compatibility: Projects without settings files work identically to before
+- **Settings File Generation**: New `specify init --settings` command generates a documented settings file
+  - Use `--force` to overwrite existing settings files
+  - Settings file includes comprehensive documentation and examples
+- **Branch Name Validation**: Generated branch names are validated against Git naming rules before creation
+  - Validates against forbidden characters, path rules, and GitHub's 244-byte limit
+  - Clear error messages for invalid configurations
+
+### Changed
+
+- `create-new-feature.sh` and `create-new-feature.ps1` now source common utility functions
+- Enhanced error messages for template configuration issues (FR-006)
+
 ## [0.0.22] - 2025-11-07
 
 - Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.

README.md

@@ -188,6 +188,7 @@ The `specify` command supports the following options:
 | `--skip-tls`           | Flag     | Skip SSL/TLS verification (not recommended)                                                                                                                                                  |
 | `--debug`              | Flag     | Enable detailed debug output for troubleshooting                                                                                                                                             |
 | `--github-token`       | Option   | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)                                                                                                                    |
+| `--settings`           | Flag     | Generate `.specify/settings.toml` for branch template customization. Can be combined with other flags.                                                                                       |
 
 ### Examples
 
@@ -238,10 +239,49 @@ specify init my-project --ai claude --debug
 # Use GitHub token for API requests (helpful for corporate environments)
 specify init my-project --ai claude --github-token ghp_your_token_here
 
+# Generate settings file for branch template customization
+specify init --settings
+
 # Check system requirements
 specify check
 ```
 
+### Branch Template Configuration
+
+Teams can customize branch naming patterns by creating a `.specify/settings.toml` file:
+
+```bash
+# Generate a settings file with documented options
+specify init --settings
+```
+
+The settings file supports the following template variables:
+
+| Variable         | Description                                                    | Example Output    |
+| ---------------- | -------------------------------------------------------------- | ----------------- |
+| `{number}`       | Auto-incrementing 3-digit feature number                       | `001`, `002`      |
+| `{short_name}`   | Generated or provided short feature name                       | `add-login`       |
+| `{username}`     | Git user.name, normalized (lowercase, hyphens)                 | `jane-smith`      |
+| `{email_prefix}` | Portion of Git user.email before the @ symbol                  | `jsmith`          |
+
+**Example templates:**
+
+```toml
+# Solo developer (default)
+template = "{number}-{short_name}"
+# Result: 001-add-login
+
+# Team with username prefix
+template = "{username}/{number}-{short_name}"
+# Result: johndoe/001-add-login
+
+# Team with feature prefix
+template = "feature/{username}/{number}-{short_name}"
+# Result: feature/johndoe/001-add-login
+```
+
+When using `{username}` or a static prefix, each prefix gets its own independent number sequence, avoiding conflicts between team members.
+
 ### Available Slash Commands
 
 After running `specify init`, your AI coding agent will have access to these slash commands for structured development:

docs/installation.md

@@ -62,6 +62,30 @@ If you prefer to get the templates without checking for the right tools:
 uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude --ignore-agent-tools
 ```
 
+### Initialize Settings File
+
+Teams can customize branch naming patterns by initializing a settings file:
+
+```bash
+# Settings file only (in current directory)
+uvx --from git+https://github.com/github/spec-kit.git specify init --settings
+
+# Combined with full project initialization
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --settings --ai copilot
+
+# Or with --here flag for existing projects
+uvx --from git+https://github.com/github/spec-kit.git specify init --here --settings --force
+```
+
+This creates `.specify/settings.toml` where you can configure the branch template:
+
+```toml
+[branch]
+template = "{username}/{number}-{short_name}"  # e.g., jsmith/001-my-feature
+```
+
+Available template variables: `{number}`, `{short_name}`, `{username}`, `{email_prefix}`
+
 ## Verification
 
 After initialization, you should see the following commands available in your AI agent:

docs/quickstart.md

@@ -29,6 +29,37 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script sh  # Force POSIX shell
 ```
 
+#### Customizing Branch Names
+
+Teams can customize how feature branches are named by initializing a settings file:
+
+```bash
+# Settings file only (current directory)
+uvx --from git+https://github.com/github/spec-kit.git specify init --settings
+
+# Combined with full project init
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --settings --ai copilot
+
+# Or with --here flag
+uvx --from git+https://github.com/github/spec-kit.git specify init --here --settings --ai claude
+```
+
+This creates `.specify/settings.toml` where you can configure the branch template:
+
+```toml
+[branch]
+template = "{username}/{number}-{short_name}"  # e.g., jsmith/001-my-feature
+```
+
+Available template variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{number}` | Auto-incrementing 3-digit number | `001` |
+| `{short_name}` | Kebab-case feature name | `my-feature` |
+| `{username}` | Git user.name or OS username | `jsmith` |
+| `{email_prefix}` | Part before @ in Git email | `john.smith` |
+
 ### Step 2: Define Your Constitution
 
 **In your AI Agent's chat interface**, use the `/speckit.constitution` slash command to establish the core rules and principles for your project. You should provide your project's specific principles as arguments.

docs/upgrade.md

@@ -61,6 +61,7 @@ These files are **never touched** by the upgrade—the template packages don't e
 
 - ✅ **Your specifications** (`specs/001-my-feature/spec.md`, etc.) - **CONFIRMED SAFE**
 - ✅ **Your implementation plans** (`specs/001-my-feature/plan.md`, `tasks.md`, etc.) - **CONFIRMED SAFE**
+- ✅ **Your settings file** (`.specify/settings.toml`) - **CONFIRMED SAFE**
 - ✅ **Your source code** - **CONFIRMED SAFE**
 - ✅ **Your git history** - **CONFIRMED SAFE**
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.0.22"
+version = "0.0.24"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [

scripts/bash/check-prerequisites.sh

@@ -80,7 +80,7 @@ source "$SCRIPT_DIR/common.sh"
 
 # Get feature paths and validate branch
 eval $(get_feature_paths)
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" "$REPO_ROOT" || exit 1
 
 # If paths-only mode, output paths and exit (support JSON + paths-only combined)
 if $PATHS_ONLY; then