Feature Creation and Branch Management

Relevant source files

• README.md
• scripts/bash/create-new-feature.sh
• scripts/powershell/create-new-feature.ps1

Purpose and Scope

This document explains how feature branches and specification directories are created in the Spec-Driven Development workflow. The create-new-feature scripts (bash and PowerShell) automatically generate sequential branch numbers, create human-readable branch names from feature descriptions, and initialize the necessary directory structure for specifications. This process occurs before the /speckit.specify command (see 5.3) generates the actual specification content.

For information about the broader cross-platform script architecture, see Cross-Platform Script Architecture.

---

Feature Creation Scripts

The system provides two functionally equivalent scripts that handle feature initialization:

Script	Path	Purpose
Bash	scripts/bash/create-new-feature.sh	Unix/Linux/macOS environments
PowerShell	scripts/powershell/create-new-feature.ps1	Windows/cross-platform environments

Both scripts are invoked by AI agents during the /speckit.specify command execution. They create a new Git branch (if Git is available), generate a unique feature number, create the specification directory structure, and initialize the spec file from a template.

Sources: scripts/bash/create-new-feature.sh1-298 scripts/powershell/create-new-feature.ps11-283

---

Command-Line Interface

Arguments and Options

Option	Type	Description
--json / -Json	Flag	Output results in JSON format instead of plain text
--short-name / -ShortName	String	Override automatic branch name generation with custom name
--number / -Number	Integer	Manually specify branch number (bypasses auto-detection)
<feature_description>	Required	Natural language description of the feature

Output Format

The scripts produce structured output containing the generated branch information:

Plain Text Mode:

BRANCH_NAME: 003-user-authentication
SPEC_FILE: /path/to/specs/003-user-authentication/spec.md
FEATURE_NUM: 003
SPECIFY_FEATURE environment variable set to: 003-user-authentication

JSON Mode (--json):

Sources: scripts/bash/create-new-feature.sh43-55 scripts/bash/create-new-feature.sh290-297 scripts/powershell/create-new-feature.ps114-28 scripts/powershell/create-new-feature.ps1268-282

---

Repository Root Resolution

The scripts must operate from anywhere within the repository hierarchy. They use a fallback strategy to locate the repository root:

Bash Implementation: find_repo_root()

This dual-mode operation ensures the scripts function in repositories initialized with --no-git, while still leveraging Git's branch tracking when available.

Sources: scripts/bash/create-new-feature.sh70-81 scripts/bash/create-new-feature.sh161-173 scripts/powershell/create-new-feature.ps141-60 scripts/powershell/create-new-feature.ps1132-148

---

Branch Number Generation

The system ensures unique, sequential branch numbers by examining both Git branches and spec directories, then selecting the next available number.

Number Detection Algorithm

Bash: get_highest_from_branches()

The function examines all branches (local and remote) to find the highest feature number:

Key operations:

1. Execute git branch -a to list all branches
2. Clean branch names: remove *, whitespace, remotes/origin/ prefixes
3. Extract numbers from branches matching pattern ^[0-9]{3}-
4. Return maximum number found (0 if no matching branches)

Sources: scripts/bash/create-new-feature.sh103-127

Bash: get_highest_from_specs()

The function scans the specs/ directory for existing feature folders:

Key operations:

1. Iterate through directories in $specs_dir
2. Extract numeric prefix from directory names with grep -o '^[0-9]\+'
3. Force base-10 interpretation with $((10#$number)) to avoid octal conversion
4. Return maximum number found

Sources: scripts/bash/create-new-feature.sh83-101

Branch Number Determination: check_existing_branches()

The function coordinates both detection methods:

This ensures the next feature number accounts for:

• Local branches that haven't been pushed
• Remote branches not yet checked out locally
• Orphaned spec directories (branches deleted but specs remain)

Sources: scripts/bash/create-new-feature.sh129-150 scripts/bash/create-new-feature.sh237-247

---

Branch Name Generation

The scripts generate human-readable branch names from natural language descriptions using stop word filtering and intelligent word selection.

Branch Name Generation Flow

Stop Word Filtering

The generate_branch_name() function removes common English words that don't contribute semantic value:

Stop word list (bash):

Algorithm:

1. Convert description to lowercase
2. Split into words (alphanumeric sequences only)
3. For each word:
   • Skip if it matches stop word regex
   • Skip if length < 3 characters (unless uppercase acronym in original)
   • Keep words ≥ 3 characters
4. Select first 3-4 meaningful words
5. Join with hyphens

Examples:

Input Description	Filtered Words	Generated Branch Name
"I want to add a user authentication system"	["user", "authentication", "system"]	NNN-user-authentication-system
"Build API for OAuth2 integration"	["build", "api", "oauth2", "integration"]	NNN-build-api-oauth2-integration
"The photo album organizing feature"	["photo", "album", "organizing", "feature"]	NNN-photo-album-organizing

Sources: scripts/bash/create-new-feature.sh180-226 scripts/powershell/create-new-feature.ps1155-198

GitHub Branch Name Length Limit

GitHub enforces a 244-byte maximum for branch names. The scripts validate and truncate names that exceed this limit:

The truncation preserves the feature number prefix and removes trailing hyphens to maintain clean branch naming.

Sources: scripts/bash/create-new-feature.sh253-272 scripts/powershell/create-new-feature.ps1224-242

---

Git vs Non-Git Operation

The scripts adapt their behavior based on Git availability, ensuring the workflow functions in both Git-managed and non-Git repositories.

Operational Modes

Git Mode Operations

When Git is available (HAS_GIT=true):

• Execute git fetch --all --prune to synchronize remote branch information
• Scan both local and remote branches for feature numbers
• Create new branch with git checkout -b $BRANCH_NAME
• Track relationship between Git branches and spec directories

Sources: scripts/bash/create-new-feature.sh163-165 scripts/bash/create-new-feature.sh239-241 scripts/bash/create-new-feature.sh274-275

Non-Git Mode Operations

When Git is unavailable (HAS_GIT=false):

• Print warning: "Git repository not detected; skipped branch creation"
• Skip all Git commands (git fetch, git checkout)
• Rely solely on specs/ directory scanning for feature numbering
• Set SPECIFY_FEATURE environment variable to track current feature
• All workflow commands use SPECIFY_FEATURE to locate the active feature directory

Sources: scripts/bash/create-new-feature.sh166-173 scripts/bash/create-new-feature.sh244-245 scripts/bash/create-new-feature.sh276-278

---

SPECIFY_FEATURE Environment Variable

In non-Git environments, the system cannot infer the current feature from the Git branch name. The SPECIFY_FEATURE environment variable provides an explicit feature context.

Variable Usage

Workflow Integration

Command	Behavior with SPECIFY_FEATURE
/speckit.specify	Uses variable to determine which specs/NNN-name/ directory to write spec.md
/speckit.plan	Reads from specs/${SPECIFY_FEATURE}/spec.md, writes to specs/${SPECIFY_FEATURE}/plan.md
/speckit.tasks	Reads from specs/${SPECIFY_FEATURE}/plan.md, writes to specs/${SPECIFY_FEATURE}/tasks.md
/speckit.implement	Reads from specs/${SPECIFY_FEATURE}/tasks.md for implementation instructions

The variable must be set in the AI agent's environment context before executing workflow commands. The agent context files (e.g., CLAUDE.md) document this requirement:

Must be set in the context of the agent you're working with prior to using /speckit.plan or follow-up commands.

Sources: scripts/bash/create-new-feature.sh288-296 scripts/powershell/create-new-feature.ps1265-281 README.md273-276

---

Directory Structure Creation

After determining the branch name and number, the scripts create the specification directory structure and initialize the spec file.

Directory Creation Flow

Implementation

The spec file is populated from the template, which contains structured sections for:

• Feature overview
• User stories
• Functional requirements
• Out of scope items
• Review & acceptance checklist

This file becomes the input for the /speckit.specify command, which fills in the template sections based on the feature description.

Sources: scripts/bash/create-new-feature.sh177-178 scripts/bash/create-new-feature.sh280-285 scripts/powershell/create-new-feature.ps1152-153 scripts/powershell/create-new-feature.ps1254-263

---

Code Entity Mapping

The following table maps high-level concepts to concrete code entities in the scripts:

Concept	Bash Implementation	PowerShell Implementation
Repository root detection	find_repo_root() scripts/bash/create-new-feature.sh70-81	Find-RepositoryRoot scripts/powershell/create-new-feature.ps141-60
Branch number from specs	get_highest_from_specs() scripts/bash/create-new-feature.sh83-101	Get-HighestNumberFromSpecs scripts/powershell/create-new-feature.ps162-75
Branch number from Git	get_highest_from_branches() scripts/bash/create-new-feature.sh103-127	Get-HighestNumberFromBranches scripts/powershell/create-new-feature.ps177-100
Next available number	check_existing_branches() scripts/bash/create-new-feature.sh129-150	Get-NextBranchNumber scripts/powershell/create-new-feature.ps1102-125
Branch name normalization	clean_branch_name() scripts/bash/create-new-feature.sh152-156	ConvertTo-CleanBranchName scripts/powershell/create-new-feature.ps1127-131
Intelligent name generation	generate_branch_name() scripts/bash/create-new-feature.sh180-226	Get-BranchName scripts/powershell/create-new-feature.ps1155-198
Feature number formatting	printf "%03d" "$((10#$BRANCH_NUMBER))" scripts/bash/create-new-feature.sh250	'{0:000}' -f $Number scripts/powershell/create-new-feature.ps1220
Git mode detection	HAS_GIT variable scripts/bash/create-new-feature.sh165	$hasGit variable scripts/powershell/create-new-feature.ps1141
Branch creation	git checkout -b "$BRANCH_NAME" scripts/bash/create-new-feature.sh275	git checkout -b $branchName scripts/powershell/create-new-feature.ps1246
Spec directory creation	mkdir -p "$FEATURE_DIR" scripts/bash/create-new-feature.sh281	New-Item -ItemType Directory -Path $featureDir -Force scripts/powershell/create-new-feature.ps1255
Template copy	cp "$TEMPLATE" "$SPEC_FILE" scripts/bash/create-new-feature.sh285	Copy-Item $template $specFile -Force scripts/powershell/create-new-feature.ps1260
Environment variable	export SPECIFY_FEATURE="$BRANCH_NAME" scripts/bash/create-new-feature.sh288	$env:SPECIFY_FEATURE = $branchName scripts/powershell/create-new-feature.ps1266
JSON output	printf '{"BRANCH_NAME":"%s",...}\n' scripts/bash/create-new-feature.sh291	ConvertTo-Json -Compress scripts/powershell/create-new-feature.ps1275

---

Integration with Workflow Commands

The feature creation scripts are automatically invoked by AI agents during the /speckit.specify command execution. The following sequence shows the integration:

Sources: scripts/bash/create-new-feature.sh1-298 scripts/powershell/create-new-feature.ps11-283