github · localden · Oct 15, 2025 · Oct 14, 2025 · Oct 14, 2025 · Oct 14, 2025
@@ -0,0 +1 @@
+* text=auto eol=lf
@@ -1,2 +1,3 @@
 # Global code owner
 * @localden
+
@@ -65,3 +65,4 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+
@@ -57,3 +57,4 @@ jobs:
         run: |
           chmod +x .github/workflows/scripts/update-version.sh
           .github/workflows/scripts/update-version.sh ${{ steps.get_tag.outputs.new_version }}
+
@@ -18,4 +18,4 @@ if gh release view "$VERSION" >/dev/null 2>&1; then
 else
   echo "exists=false" >> $GITHUB_OUTPUT
   echo "Release $VERSION does not exist, proceeding..."
-fi
+fi
@@ -43,4 +43,4 @@ gh release create "$VERSION" \
   .genreleases/spec-kit-template-q-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-q-ps-"$VERSION".zip \
   --title "Spec Kit Templates - $VERSION_NO_V" \
-  --notes-file release_notes.md
+  --notes-file release_notes.md
@@ -237,3 +237,4 @@ done
 
 echo "Archives in $GENRELEASES_DIR:"
 ls -1 "$GENRELEASES_DIR"/spec-kit-template-*-"${NEW_VERSION}".zip
+
@@ -33,4 +33,4 @@ This is the latest set of releases that you can use with your agent of choice. W
 EOF
 
 echo "Generated release notes:"
-cat release_notes.md
+cat release_notes.md
@@ -21,4 +21,4 @@ PATCH=$((PATCH + 1))
 NEW_VERSION="v$MAJOR.$MINOR.$PATCH"
 
 echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-echo "New version will be: $NEW_VERSION"
+echo "New version will be: $NEW_VERSION"
@@ -20,4 +20,4 @@ if [ -f "pyproject.toml" ]; then
   echo "Updated pyproject.toml version to $PYTHON_VERSION (for release artifacts only)"
 else
   echo "Warning: pyproject.toml not found, skipping version update"
-fi
+fi
@@ -42,4 +42,4 @@ env/
 # Spec Kit-specific files
 .genreleases/
 *.zip
-sdd-*/
+sdd-*/
@@ -326,3 +326,4 @@ When adding new agents:
 ---
 
 *This documentation should be updated whenever new agents are added to maintain accuracy and completeness.*
+
@@ -7,6 +7,29 @@ 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.20] - 2025-10-14
+
+### Added
+
+- **Intelligent Branch Naming**: `create-new-feature` scripts now support `--short-name` parameter for custom branch names
+  - When `--short-name` provided: Uses the custom name directly (cleaned and formatted)
+  - When omitted: Automatically generates meaningful names using stop word filtering and length-based filtering
+  - Filters out common stop words (I, want, to, the, for, etc.)
+  - Removes words shorter than 3 characters (unless they're uppercase acronyms)
+  - Takes 3-4 most meaningful words from the description
+  - **Enforces GitHub's 244-byte branch name limit** with automatic truncation and warnings
+  - Examples:
+    - "I want to create user authentication" → `001-create-user-authentication`
+    - "Implement OAuth2 integration for API" → `001-implement-oauth2-integration-api`
+    - "Fix payment processing bug" → `001-fix-payment-processing`
+    - Very long descriptions are automatically truncated at word boundaries to stay within limits
+  - Designed for AI agents to provide semantic short names while maintaining standalone usability
+
+### Changed
+
+- Enhanced help documentation for `create-new-feature.sh` and `create-new-feature.ps1` scripts with examples
+- Branch names now validated against GitHub's 244-byte limit with automatic truncation if needed
+
 ## [0.0.19] - 2025-10-10
 
 ### Added
@@ -143,3 +166,4 @@ N/A
 ### Changed
 
 N/A
+
@@ -71,4 +71,4 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], versi
 available at [http://contributor-covenant.org/version/1/4][version]
 
 [homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+[version]: http://contributor-covenant.org/version/1/4/
@@ -108,3 +108,4 @@ Please be respectful to maintainers and disclose AI assistance.
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
 - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
 - [GitHub Help](https://help.github.com)
+
@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
@@ -5,7 +5,7 @@
 </div>
 
 <p align="center">
-    <strong>An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.</strong>
+    <strong>An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.</strong>
-    <strong>An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.</strong>
+    <strong>An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of ad-hoc coding every piece from scratch.</strong>
-    <strong>An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.</strong>
+    <strong>An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of ad-hoc coding every piece from scratch.</strong>
 </p>
 
 <p align="center">
@@ -42,7 +42,7 @@ Spec-Driven Development **flips the script** on traditional software development
 
 ## ⚡ Get started
 
-### 1. Install Specify
+### 1. Install Specify CLI
 
 Choose your preferred installation method:
 
@@ -623,3 +623,4 @@ This project is heavily influenced by and based on the work and research of [Joh
 ## 📄 License
 
 This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
+
@@ -28,4 +28,4 @@ This information will help us triage your report more quickly.
 
 ## Policy
 
-See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)
+See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)
@@ -17,3 +17,4 @@ For help or questions about using this project, please:
 ## GitHub Support Policy
 
 Support for this project is limited to the resources listed above.
+
@@ -6,3 +6,4 @@ obj/
 # Temporary files
 *.tmp
 *.log
+
@@ -31,3 +31,4 @@ To build the documentation locally:
 ## Deployment
 
 Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch. The workflow is defined in `.github/workflows/docs.yml`.
+
@@ -68,3 +68,4 @@
     }
   }
 }
+
@@ -60,3 +60,4 @@ Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main
 ## Support
 
 For support, please check our [Support Guide](https://github.com/github/spec-kit/blob/main/SUPPORT.md) or open an issue on GitHub.
+
@@ -86,3 +86,4 @@ git config --global credential.helper manager
 echo "Cleaning up..."
 rm gcm-linux_amd64.2.6.1.deb
 ```
+
@@ -166,3 +166,4 @@ rm -rf .venv dist build *.egg-info
 - Open a PR when satisfied
 - (Optional) Tag a release once changes land in `main`
 
+
@@ -120,3 +120,4 @@ implement specs/002-create-taskify/plan.md
 - Read the complete methodology for in-depth guidance
 - Check out more examples in the repository
 - Explore the source code on GitHub
+
@@ -15,3 +15,4 @@
   items:
     - name: Local Development
       href: local-development.md
+
@@ -47,4 +47,4 @@
 <!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
 
 **Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.0.19"
+version = "0.0.20"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
@@ -21,3 +21,4 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/specify_cli"]
+
@@ -163,4 +163,4 @@ else
     if $INCLUDE_TASKS; then
         check_file "$TASKS" "tasks.md"
     fi
-fi
+fi
@@ -111,3 +111,4 @@ EOF
 
 check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
 check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+
@@ -3,18 +3,46 @@
 set -e
 
 JSON_MODE=false
+SHORT_NAME=""
 ARGS=()
-for arg in "$@"; do
+i=0
+while [ $i -lt $# ]; do
+    arg="${!i}"
     case "$arg" in
-        --json) JSON_MODE=true ;;
-        --help|-h) echo "Usage: $0 [--json] <feature_description>"; exit 0 ;;
-        *) ARGS+=("$arg") ;;
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -ge $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            SHORT_NAME="${!i}"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API'"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
     esac
+    i=$((i + 1))
 done
 
 FEATURE_DESCRIPTION="${ARGS[*]}"
 if [ -z "$FEATURE_DESCRIPTION" ]; then
-    echo "Usage: $0 [--json] <feature_description>" >&2
+    echo "Usage: $0 [--json] [--short-name <name>] <feature_description>" >&2
     exit 1
 fi
 
@@ -67,9 +95,84 @@ fi
 NEXT=$((HIGHEST + 1))
 FEATURE_NUM=$(printf "%03d" "$NEXT")
 
-BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
-WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//')
-BRANCH_NAME="${FEATURE_NUM}-${WORDS}"
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
+            elif echo "$description" | grep -q "\b$(echo "$word" | tr '[:lower:]' '[:upper:]')\b"; then
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
+            elif echo "$description" | grep -q "\b$(echo "$word" | tr '[:lower:]' '[:upper:]')\b"; then
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
+            elif echo "$description" | grep -q "\b$(echo "$word" | tr '[:lower:]' '[:upper:]')\b"; then
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
+            elif echo "$description" | grep -q "\b$(echo "$word" | tr '[:lower:]' '[:upper:]')\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//' | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(echo "$SHORT_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+
+    >&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)"
+fi
 
 if [ "$HAS_GIT" = true ]; then
     git checkout -b "$BRANCH_NAME"
@@ -94,4 +197,4 @@ else
     echo "SPEC_FILE: $SPEC_FILE"
     echo "FEATURE_NUM: $FEATURE_NUM"
     echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
-fi
+fi
@@ -58,3 +58,4 @@ else
     echo "BRANCH: $CURRENT_BRANCH"
     echo "HAS_GIT: $HAS_GIT"
 fi
+
@@ -736,3 +736,4 @@ main() {
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
     main "$@"
 fi
+
@@ -145,4 +145,4 @@ if ($Json) {
     if ($IncludeTasks) {
         Test-FileExists -Path $paths.TASKS -Description 'tasks.md' | Out-Null
     }
-}
+}
@@ -134,3 +134,4 @@ function Test-DirHasFiles {
         return $false
     }
 }
+
Original file line number	Diff line number	Diff line change
Expand Up		@@ -65,3 +65,4 @@ jobs:
		- name: Deploy to GitHub Pages
		id: deployment
		uses: actions/deploy-pages@v4
Original file line number	Diff line number	Diff line change
Expand Up		@@ -57,3 +57,4 @@ jobs:
		run: \|
		chmod +x .github/workflows/scripts/update-version.sh
		.github/workflows/scripts/update-version.sh ${{ steps.get_tag.outputs.new_version }}
-Original file line number
+Diff line change
@@ Expand Up / @@ -18,4 +18,4 @@ if gh release view "$VERSION" >/dev/null 2>&1; then @@
     else
       echo "exists=false" >> $GITHUB_OUTPUT
       echo "Release $VERSION does not exist, proceeding..."
-    fi
+    fi
Original file line number	Diff line number	Diff line change
Expand Up		@@ -237,3 +237,4 @@ done

		echo "Archives in $GENRELEASES_DIR:"
		ls -1 "$GENRELEASES_DIR"/spec-kit-template-*-"${NEW_VERSION}".zip
Original file line number	Diff line number	Diff line change
Expand Up		@@ -326,3 +326,4 @@ When adding new agents:
		---

		This documentation should be updated whenever new agents are added to maintain accuracy and completeness.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -108,3 +108,4 @@ Please be respectful to maintainers and disclose AI assistance.
		- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
		- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
		- [GitHub Help](https://help.github.com)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
		LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
		OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
		SOFTWARE.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -28,4 +28,4 @@ This information will help us triage your report more quickly.

		## Policy

		See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)
		See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -17,3 +17,4 @@ For help or questions about using this project, please:
		## GitHub Support Policy

		Support for this project is limited to the resources listed above.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -31,3 +31,4 @@ To build the documentation locally:
		## Deployment

		Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch. The workflow is defined in `.github/workflows/docs.yml`.