Spec Kit: support nested specs/<category>/<NNN-name>

scripts/bash/common.sh

@@ -34,19 +34,18 @@ get_current_branch() {
         local latest_feature=""
         local highest=0
 
-        for dir in "$specs_dir"/*; do
-            if [[ -d "$dir" ]]; then
-                local dirname=$(basename "$dir")
-                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
-                    local number=${BASH_REMATCH[1]}
-                    number=$((10#$number))
-                    if [[ "$number" -gt "$highest" ]]; then
-                        highest=$number
-                        latest_feature=$dirname
-                    fi
+        while IFS= read -r dir; do
+            [[ -d "$dir" ]] || continue
+            local dirname=$(basename "$dir")
+            if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                local number=${BASH_REMATCH[1]}
+                number=$((10#$number))
+                if [[ "$number" -gt "$highest" ]]; then
+                    highest=$number
+                    latest_feature=$dirname
                 fi
             fi
-        done
+        done < <(find "$specs_dir" -mindepth 1 -maxdepth 2 -type d 2>/dev/null)
 
         if [[ -n "$latest_feature" ]]; then
             echo "$latest_feature"
@@ -99,13 +98,20 @@ find_feature_dir_by_prefix() {
 
     local prefix="${BASH_REMATCH[1]}"
 
-    # Search for directories in specs/ that start with this prefix
     local matches=()
     if [[ -d "$specs_dir" ]]; then
+        if [[ -n "${SPECIFY_SPECS_SUBDIR:-}" ]] && [[ -d "$specs_dir/$SPECIFY_SPECS_SUBDIR" ]]; then
+            for dir in "$specs_dir/$SPECIFY_SPECS_SUBDIR"/"$prefix"-*; do
+                [[ -d "$dir" ]] && matches+=("$dir")
+            done
+        fi
+
         for dir in "$specs_dir"/"$prefix"-*; do
-            if [[ -d "$dir" ]]; then
-                matches+=("$(basename "$dir")")
-            fi
+            [[ -d "$dir" ]] && matches+=("$dir")
+        done
+
+        for dir in "$specs_dir"/*/"$prefix"-*; do
+            [[ -d "$dir" ]] && matches+=("$dir")
         done
     fi
 
@@ -115,7 +121,7 @@ find_feature_dir_by_prefix() {
         echo "$specs_dir/$branch_name"
     elif [[ ${#matches[@]} -eq 1 ]]; then
         # Exactly one match - perfect!
-        echo "$specs_dir/${matches[0]}"
+        echo "${matches[0]}"
     else
         # Multiple matches - this shouldn't happen with proper naming convention
         echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2

scripts/bash/create-new-feature.sh

@@ -5,6 +5,7 @@ set -e
 JSON_MODE=false
 SHORT_NAME=""
 BRANCH_NUMBER=""
+SPECS_SUBDIR=""
 ARGS=()
 i=1
 while [ $i -le $# ]; do
@@ -40,18 +41,34 @@ while [ $i -le $# ]; do
             fi
             BRANCH_NUMBER="$next_arg"
             ;;
+        --specs-subdir)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --specs-subdir requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --specs-subdir requires a value' >&2
+                exit 1
+            fi
+            SPECS_SUBDIR="$next_arg"
+            ;;
         --help|-h) 
-            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] [--specs-subdir <path>] <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 "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --specs-subdir <path> Create feature under specs/<path>/ (e.g. 'libraries')"
             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' --number 5"
+            echo "  $0 'Add firebird client' --specs-subdir 'libraries'"
             exit 0
             ;;
         *) 
@@ -86,15 +103,15 @@ get_highest_from_specs() {
     local highest=0
 
     if [ -d "$specs_dir" ]; then
-        for dir in "$specs_dir"/*; do
+        while IFS= read -r dir; do
             [ -d "$dir" ] || continue
             dirname=$(basename "$dir")
             number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
             number=$((10#$number))
             if [ "$number" -gt "$highest" ]; then
                 highest=$number
             fi
-        done
+        done < <(find "$specs_dir" -mindepth 1 -maxdepth 2 -type d 2>/dev/null)
     fi
 
     echo "$highest"
@@ -177,6 +194,11 @@ cd "$REPO_ROOT"
 SPECS_DIR="$REPO_ROOT/specs"
 mkdir -p "$SPECS_DIR"
 
+# Normalize specs subdir to avoid accidental paths like "libraries:" or trailing slashes
+if [ -n "$SPECS_SUBDIR" ]; then
+    SPECS_SUBDIR="$(echo "$SPECS_SUBDIR" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//; s/:$//; s#^/*##; s#/*$##')"
+fi
+
 # Function to generate branch name with stop word filtering and length filtering
 generate_branch_name() {
     local description="$1"
@@ -250,6 +272,11 @@ fi
 FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
 BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
 
+if [ -z "$BRANCH_NAME" ] || ! echo "$BRANCH_NAME" | grep -qE '^[0-9]{3}-'; then
+    echo "Error: Failed to compute valid BRANCH_NAME (got '$BRANCH_NAME')" >&2
+    exit 1
+fi
+
 # GitHub enforces a 244-byte limit on branch names
 # Validate and truncate if necessary
 MAX_BRANCH_LENGTH=244
@@ -277,7 +304,11 @@ else
     >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
 fi
 
-FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+if [ -n "$SPECS_SUBDIR" ]; then
+    FEATURE_DIR="$SPECS_DIR/$SPECS_SUBDIR/$BRANCH_NAME"
+else
+    FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+fi
 mkdir -p "$FEATURE_DIR"
 
 TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
@@ -286,12 +317,14 @@ if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"
 
 # Set the SPECIFY_FEATURE environment variable for the current session
 export SPECIFY_FEATURE="$BRANCH_NAME"
+export SPECIFY_SPECS_SUBDIR="$SPECS_SUBDIR"
 
 if $JSON_MODE; then
-    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
+    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s","SPECS_SUBDIR":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM" "$SPECS_SUBDIR"
 else
     echo "BRANCH_NAME: $BRANCH_NAME"
     echo "SPEC_FILE: $SPEC_FILE"
     echo "FEATURE_NUM: $FEATURE_NUM"
+    echo "SPECS_SUBDIR: $SPECS_SUBDIR"
     echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
 fi

templates/commands/specify.md

@@ -8,9 +8,6 @@ handoffs:
     agent: speckit.clarify
     prompt: Clarify specification requirements
     send: true
-scripts:
-  sh: scripts/bash/create-new-feature.sh --json "{ARGS}"
-  ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"
 ---
 
 ## User Input
@@ -23,12 +20,26 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Outline
 
-The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+The text the user typed after `/speckit.specify` in the triggering message **is** the input. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+This workflow supports an optional `category:` prefix to create the feature under `specs/<category>/...`.
+
+Examples:
+- `/speckit.specify Add user authentication` -> create in `specs/<NNN-name>/...` (default behavior)
+- `/speckit.specify libraries: Add firebird client` -> create in `specs/libraries/<NNN-name>/...`
+
+Parsing rules:
+- If the input matches `^<category>:\s+<description>$`, then:
+  - `SPECS_SUBDIR=<category>` (used as `--specs-subdir` when calling create script)
+  - `FEATURE_DESCRIPTION=<description>` (used for short-name generation + spec content)
+- Otherwise:
+  - `SPECS_SUBDIR` is empty
+  - `FEATURE_DESCRIPTION` is the full input
 
 Given that feature description, do this:
 
 1. **Generate a concise short name** (2-4 words) for the branch:
-   - Analyze the feature description and extract the most meaningful keywords
+   - Analyze `FEATURE_DESCRIPTION` (NOT including the optional `category:` prefix) and extract the most meaningful keywords
    - Create a 2-4 word short name that captures the essence of the feature
    - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
    - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
@@ -47,31 +58,28 @@ Given that feature description, do this:
       git fetch --all --prune
       ```
 
-   b. Find the highest feature number across all sources for the short-name:
-      - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
-      - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
-      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
-
-   c. Determine the next available number:
-      - Extract all numbers from all three sources
-      - Find the highest number N
-      - Use N+1 for the new branch number
+   b. Feature numbers are global (shared across all features), not per short-name.
 
-   d. Run the script `{SCRIPT}` with the calculated number and short-name:
-      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
-      - Bash example: `{SCRIPT} --json --number 5 --short-name "user-auth" "Add user authentication"`
-      - PowerShell example: `{SCRIPT} -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+   c. Run the script `.specify/scripts/bash/create-new-feature.sh` and let it auto-detect the next available number globally (it checks git branches + specs directories, including nested specs):
+      - Always pass:
+        - `--json`
+        - `--short-name "<short-name>"`
+        - `"FEATURE_DESCRIPTION"`
+      - If `SPECS_SUBDIR` is non-empty, also pass:
+        - `--specs-subdir "<category>"`
+      - Bash example (no category):
+        `.specify/scripts/bash/create-new-feature.sh --json --short-name "user-auth" "Add user authentication"`
+      - Bash example (with category):
+        `.specify/scripts/bash/create-new-feature.sh --json --short-name "firebird-client" --specs-subdir "libraries" "Add firebird client"`
 
    **IMPORTANT**:
-   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
-   - Only match branches/directories with the exact short-name pattern
-   - If no existing branches/directories found with this short-name, start with number 1
+   - The script will check all sources to find the highest number and pick the next one
    - You must only ever run this script once per feature
    - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
    - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
    - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
 
-3. Load `templates/spec-template.md` to understand required sections.
+3. Load `.specify/templates/spec-template.md` to understand required sections.
 
 4. Follow this execution flow: