Feature/configure branch name #1009

ricardojmendez · 2025-10-22T08:08:42Z

Contains several commits allowing the user to specify some values around branch and spec name:

Branch prefix, allowing for feature/, bugfix/, or other patterns to match the user's / team's approach;
An arbitrary spec number, to potentially tie it into the corresponding issue on Github, instead of just using a sequence.

It also includes an optional configuration file for default branch name, since I expect users will create one type of branch more often than others (eg. "feature").

This addresses some of the requests in #407.

When running 'specify', the user can now indicate a branch prefix to use, in case they have in-house naming conventions for branches. Examples: /speckit.specify a feature. Add this stuff. /speckit.specify --branch-prefix bugfix. Solve the crash in fizzbuzz. It also introduces a config file so that you can configure your default branch names, since I personally end up defaulting to "feature" most of the time.

This allows you to create branches which have a number that matches your issue number in Github (or any other tracker).

This makes it clearer that the user may enter input such as: - "Branch type feature, number 303" or - "This is bugfix 31416" It should also allow for timestamp hotfixes, given they're only a number.

Copilot

Pull Request Overview

This PR adds configuration capabilities for customizing branch naming patterns and spec numbers in the Specify CLI tool. The changes enable users to set default branch prefixes (e.g., feature/, bugfix/) and specify custom spec numbers to align with issue trackers.

Key changes:

Introduced .specify/config.json for project-wide branch prefix configuration
Added --branch-prefix and --spec-number parameters to creation scripts
Enhanced AI agent instructions to parse natural language patterns like "feature 303" or "bugfix 666"

Reviewed Changes

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

Show a summary per file

File	Description
templates/config.json	New configuration file template with branch prefix setting
templates/commands/specify.md	Extensive documentation for parsing spec numbers and branch prefixes from user input
src/specify_cli/init.py	Added `setup_config_file()` function to copy config template during initialization
scripts/powershell/create-new-feature.ps1	Implemented config parsing and new parameters for branch customization
scripts/bash/create-new-feature.sh	Bash equivalent of PowerShell script changes
pyproject.toml	Version bump to 0.0.21
README.md	Documentation for new configuration features and usage examples
CHANGELOG.md	Release notes for version 0.0.21

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-22T08:10:08Z

templates/commands/specify.md

+  - "hotfix 42" → extract prefix `hotfix/` and number `42`
+  - "fix 123" → extract prefix `bugfix/` and number `123` (normalize "fix" to "bugfix")
+  - "chore 999" → extract prefix `chore/` and number `999`
+


The natural language pattern documentation states that "fix" normalizes to "bugfix/" (line 29), but line 69 lists both "bugfix" and "fix" as separate recognized prefix types that map to "bugfix/". This creates ambiguity about whether "fix" is a valid pattern on its own or only when followed by a number. Consider clarifying the distinction between "fix" as a standalone prefix keyword versus its use in natural language patterns.

Suggested change

> **Note:** In natural language patterns, the prefix "fix" is always normalized to "bugfix/" for consistency (e.g., "fix 123" becomes "bugfix/123"). "fix" is not accepted as a standalone prefix; use "bugfix" for explicit prefix specification.

Copilot · 2025-10-22T08:10:08Z

scripts/bash/create-new-feature.sh

+        # Use grep and sed to extract the prefix value from JSON
+        # This avoids requiring jq to be installed
+        local prefix=$(grep -o '"prefix"[[:space:]]*:[[:space:]]*"[^"]*"' "$config_file" | sed 's/.*"prefix"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')


The JSON parsing logic fails when the prefix value contains escaped quotes or special characters. For example, a prefix value of "test\"value" would break the regex pattern. While unlikely in typical branch prefix usage, consider adding validation or a comment warning about this limitation.

Suggested change

# Use grep and sed to extract the prefix value from JSON

# This avoids requiring jq to be installed

local prefix=$(grep -o '"prefix"[[:space:]]*:[[:space:]]*"[^"]*"' "$config_file" | sed 's/.*"prefix"[[:space:]]*:[[:space:]]*"$[^"]*$".*/\1/')

# Use jq to extract the prefix value from JSON. jq correctly handles escaped quotes and special characters.

# If jq is not available, fall back to grep/sed but warn about limitations.

local prefix=""

if command -v jq >/dev/null 2>&1; then

prefix=$(jq -r '.prefix // empty' "$config_file")

else

echo "Warning: jq not found. Falling back to regex-based JSON parsing, which may fail for escaped quotes or special characters in the prefix value." >&2

# Fallback: regex-based extraction (does not handle escaped quotes/special chars)

prefix=$(grep -o '"prefix"[[:space:]]*:[[:space:]]*"[^"]*"' "$config_file" | sed 's/.*"prefix"[[:space:]]*:[[:space:]]*"$[^"]*$".*/\1/')

fi

Copilot · 2025-10-22T08:10:09Z

scripts/powershell/create-new-feature.ps1

+    if ($SpecNumber) {
+        # Validate it's a positive integer
+        $num = 0
+        if (-not [int]::TryParse($SpecNumber, [ref]$num) -or $num -lt 0) {


The validation check allows zero as a valid spec number ($num -lt 0), but spec numbers starting at 0 could create ambiguous directory names like 000-feature-name. Consider changing the condition to $num -le 0 to require positive integers starting from 1.

Copilot · 2025-10-22T08:10:09Z

scripts/bash/create-new-feature.sh

+        if ! [[ "$SPEC_NUM_ARG" =~ ^[0-9]+$ ]]; then
+            echo "Error: --spec-number must be a positive integer" >&2


The bash validation allows zero as a valid spec number (regex ^[0-9]+$ matches "0"), but this could create ambiguous directory names like 000-feature-name. The PowerShell version has the same issue. Both scripts should reject zero to ensure spec numbers start from 1.

Suggested change

if ! [[ "$SPEC_NUM_ARG" =~ ^[0-9]+$ ]]; then

echo "Error: --spec-number must be a positive integer" >&2

if ! [[ "$SPEC_NUM_ARG" =~ ^[1-9][0-9]*$ ]]; then

echo "Error: --spec-number must be a positive integer greater than zero" >&2

ricardojmendez added 4 commits October 22, 2025 09:33

Feature: we can now specify a spec number

7fdc1f4

This allows you to create branches which have a number that matches your issue number in Github (or any other tracker).

Expanded specify to given natural language examples

18cb593

This makes it clearer that the user may enter input such as: - "Branch type feature, number 303" or - "This is bugfix 31416" It should also allow for timestamp hotfixes, given they're only a number.

Bumping pyproject.toml version

0951aa9

ricardojmendez requested a review from localden as a code owner October 22, 2025 08:08

Copilot AI review requested due to automatic review settings October 22, 2025 08:08

Copilot AI reviewed Oct 22, 2025

View reviewed changes

djeffersonx approved these changes Oct 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feature/configure branch name #1009

Feature/configure branch name #1009

ricardojmendez commented Oct 22, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 22, 2025

Uh oh!

Copilot AI Oct 22, 2025

Uh oh!

Copilot AI Oct 22, 2025

Uh oh!

Copilot AI Oct 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants



	> Note: In natural language patterns, the prefix "fix" is always normalized to "bugfix/" for consistency (e.g., "fix 123" becomes "bugfix/123"). "fix" is not accepted as a standalone prefix; use "bugfix" for explicit prefix specification.

-        # Use grep and sed to extract the prefix value from JSON
-        # This avoids requiring jq to be installed
-        local prefix=$(grep -o '"prefix"[[:space:]]*:[[:space:]]*"[^"]*"' "$config_file" | sed 's/.*"prefix"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+        # Use jq to extract the prefix value from JSON. jq correctly handles escaped quotes and special characters.
+        # If jq is not available, fall back to grep/sed but warn about limitations.
+        local prefix=""
+        if command -v jq >/dev/null 2>&1; then
+            prefix=$(jq -r '.prefix // empty' "$config_file")
+        else
+            echo "Warning: jq not found. Falling back to regex-based JSON parsing, which may fail for escaped quotes or special characters in the prefix value." >&2
+            # Fallback: regex-based extraction (does not handle escaped quotes/special chars)
+            prefix=$(grep -o '"prefix"[[:space:]]*:[[:space:]]*"[^"]*"' "$config_file" | sed 's/.*"prefix"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+        fi

		if ! [[ "$SPEC_NUM_ARG" =~ ^[0-9]+$ ]]; then
		echo "Error: --spec-number must be a positive integer" >&2

Feature/configure branch name #1009

Are you sure you want to change the base?

Feature/configure branch name #1009

Conversation

ricardojmendez commented Oct 22, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants