Skip to content

💫 Toolkit to help you get started with SDD or any other process!

fix(plan): use .specify/feature.json to allow /speckit.plan on custom git branches (#2305) (#2349)

Adrian Osorio Blanchard37745ec2ee2c
diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh
index cad10bdb3..03141e446 100644
--- a/scripts/bash/common.sh
+++ b/scripts/bash/common.sh
@@ -153,6 +153,59 @@ check_feature_branch() {
return 0
}
+# Safely read .specify/feature.json's "feature_directory" value.
+# Prints the raw value (possibly relative) to stdout, or empty string if the file
+# is missing, unparseable, or does not contain the key. Always returns 0 so callers
+# under `set -e` cannot be aborted by parser failure.
+# Parser order mirrors the historical get_feature_paths behavior: jq -> python3 -> grep/sed.
+read_feature_json_feature_directory() {
+ local repo_root="$1"
+ local fj="$repo_root/.specify/feature.json"
+ [[ -f "$fj" ]] || { printf '%s' ''; return 0; }
+
+ local _fd=''
+ if command -v jq >/dev/null 2>&1; then
+ if ! _fd=$(jq -r '.feature_directory // empty' "$fj" 2>/dev/null); then
+ _fd=''
+ fi
+ elif command -v python3 >/dev/null 2>&1; then
+ # Use Python so pretty-printed/multi-line JSON still parses correctly.
+ if ! _fd=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); v=d.get('feature_directory'); print(v if v else '')" "$fj" 2>/dev/null); then
+ _fd=''
+ fi
+ else
+ # Last-resort single-line grep/sed fallback. The `|| true` guards against
+ # grep returning 1 (no match) aborting under `set -e` / `pipefail`.
+ _fd=$( { grep -E '"feature_directory"[[:space:]]*:' "$fj" 2>/dev/null || true; } \
+ | head -n 1 \
+ | sed -E 's/^[^:]*:[[:space:]]*"([^"]*)".*$/\1/' )
+ fi
+
+ printf '%s' "$_fd"
+ return 0
+}
+
+# Returns 0 when .specify/feature.json lists feature_directory that exists as a directory
+# and matches the resolved active FEATURE_DIR (so /speckit.plan can skip git branch pattern checks).
+# Delegates parsing to read_feature_json_feature_directory, which is safe under `set -e`.
+feature_json_matches_feature_dir() {
+ local repo_root="$1"
+ local active_feature_dir="$2"
+
+ local _fd
+ _fd=$(read_feature_json_feature_directory "$repo_root")
+
+ [[ -n "$_fd" ]] || return 1
+ [[ "$_fd" != /* ]] && _fd="$repo_root/$_fd"
+ [[ -d "$_fd" ]] || return 1
+
+ local norm_json norm_active
+ norm_json="$(cd -- "$_fd" 2>/dev/null && pwd -P)" || return 1
+ norm_active="$(cd -- "$active_feature_dir" 2>/dev/null && pwd -P)" || return 1
+
+ [[ "$norm_json" == "$norm_active" ]]
+}
+
# Find feature directory by numeric prefix instead of exact branch match
# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
find_feature_dir_by_prefix() {
@@ -217,16 +270,10 @@ get_feature_paths() {
# Normalize relative paths to absolute under repo root
[[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"
elif [[ -f "$repo_root/.specify/feature.json" ]]; then
+ # Shared, set -e-safe parser: jq -> python3 -> grep/sed. Returns empty on
+ # missing/unparseable/unset so we fall through to the branch-prefix lookup.
local _fd
- if command -v jq >/dev/null 2>&1; then
- _fd=$(jq -r '.feature_directory // empty' "$repo_root/.specify/feature.json" 2>/dev/null)
- elif command -v python3 >/dev/null 2>&1; then
- # Fallback: use Python to parse JSON so pretty-printed/multi-line files work
- _fd=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d.get('feature_directory',''))" "$repo_root/.specify/feature.json" 2>/dev/null)
- else
- # Last resort: single-line grep fallback (won't work on multi-line JSON)
- _fd=$(grep -o '"feature_directory"[[:space:]]*:[[:space:]]*"[^"]*"' "$repo_root/.specify/feature.json" 2>/dev/null | sed 's/.*"\([^"]*\)"$/\1/')
- fi
+ _fd=$(read_feature_json_feature_directory "$repo_root")
if [[ -n "$_fd" ]]; then
feature_dir="$_fd"
# Normalize relative paths to absolute under repo root
diff --git a/scripts/bash/setup-plan.sh b/scripts/bash/setup-plan.sh
index 9f5523149..f2d2f6e6f 100644
--- a/scripts/bash/setup-plan.sh
+++ b/scripts/bash/setup-plan.sh
@@ -32,8 +32,10 @@ _paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature p
eval "$_paths_output"
unset _paths_output
-# Check if we're on a proper feature branch (only for git repos)
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+# If feature.json pins an existing feature directory, branch naming is not required.
+if ! feature_json_matches_feature_dir "$REPO_ROOT" "$FEATURE_DIR"; then
+ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+fi
# Ensure the feature directory exists
mkdir -p "$FEATURE_DIR"
diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1
index d799e4f7e..ffc6d73b3 100644
--- a/scripts/powershell/common.ps1
+++ b/scripts/powershell/common.ps1
@@ -164,6 +164,74 @@ function Test-FeatureBranch {
return $true
}
+# True when .specify/feature.json pins an existing feature directory that matches the
+# active FEATURE_DIR from Get-FeaturePathsEnv (so /speckit.plan can skip git branch pattern checks).
+function Test-FeatureJsonMatchesFeatureDir {
+ param(
+ [Parameter(Mandatory = $true)][string]$RepoRoot,
+ [Parameter(Mandatory = $true)][string]$ActiveFeatureDir
+ )
+
+ $featureJson = Join-Path (Join-Path $RepoRoot '.specify') 'feature.json'
+ if (-not (Test-Path -LiteralPath $featureJson -PathType Leaf)) {
+ return $false
+ }
+
+ try {
+ $raw = Get-Content -LiteralPath $featureJson -Raw
+ $cfg = $raw | ConvertFrom-Json
+ } catch {
+ return $false
+ }
+
+ $fd = $cfg.feature_directory
+ if ([string]::IsNullOrWhiteSpace([string]$fd)) {
+ return $false
+ }
+
+ if (-not [System.IO.Path]::IsPathRooted($fd)) {
+ $fd = Join-Path $RepoRoot $fd
+ }
+
+ if (-not (Test-Path -LiteralPath $fd -PathType Container)) {
+ return $false
+ }
+
+ # Resolve both paths to canonical absolute form. Prefer Resolve-Path (follows
+ # symlinks and is the canonical PS way); fall back to [Path]::GetFullPath when
+ # Resolve-Path can't produce a value. Mirrors the pattern used by Find-SpecifyRoot.
+ $resolvedJson = Resolve-Path -LiteralPath $fd -ErrorAction SilentlyContinue
+ if ($resolvedJson) {
+ $normJson = $resolvedJson.Path
+ } else {
+ $normJson = [System.IO.Path]::GetFullPath($fd)
+ }
+
+ $resolvedActive = Resolve-Path -LiteralPath $ActiveFeatureDir -ErrorAction SilentlyContinue
+ if ($resolvedActive) {
+ $normActive = $resolvedActive.Path
+ } else {
+ $normActive = [System.IO.Path]::GetFullPath($ActiveFeatureDir)
+ }
+
+ # Use case-insensitive compare only on Windows; POSIX filesystems are case-sensitive.
+ # PowerShell 5.1 is Windows-only and does not define $IsWindows, so treat its
+ # absence as "we're on Windows".
+ if ($null -ne $IsWindows) {
+ $onWindows = $IsWindows
+ } else {
+ $onWindows = $true
+ }
+
+ if ($onWindows) {
+ $comparison = [System.StringComparison]::OrdinalIgnoreCase
+ } else {
+ $comparison = [System.StringComparison]::Ordinal
+ }
+
+ return [string]::Equals($normJson, $normActive, $comparison)
+}
+
# Resolve specs/<feature-dir> by numeric/timestamp prefix (mirrors scripts/bash/common.sh find_feature_dir_by_prefix).
function Find-FeatureDirByPrefix {
param(
diff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1
index ee09094bf..15ae55754 100644
--- a/scripts/powershell/setup-plan.ps1
+++ b/scripts/powershell/setup-plan.ps1
@@ -23,9 +23,11 @@ if ($Help) {
# Get all paths and variables from common functions
$paths = Get-FeaturePathsEnv
-# Check if we're on a proper feature branch (only for git repos)
-if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GIT)) {
- exit 1
+# If feature.json pins an existing feature directory, branch naming is not required.
+if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFeatureDir $paths.FEATURE_DIR)) {
+ if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GIT)) {
+ exit 1
+ }
}
# Ensure the feature directory exists
diff --git a/tests/test_setup_plan_feature_json.py b/tests/test_setup_plan_feature_json.py
new file mode 100644
index 000000000..0203b3670
--- /dev/null
+++ b/tests/test_setup_plan_feature_json.py
@@ -0,0 +1,202 @@
+"""Tests for setup-plan bypassing branch-pattern checks when feature.json is valid."""
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from tests.conftest import requires_bash
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
+SETUP_PLAN_SH = PROJECT_ROOT / "scripts" / "bash" / "setup-plan.sh"
+COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
+SETUP_PLAN_PS = PROJECT_ROOT / "scripts" / "powershell" / "setup-plan.ps1"
+PLAN_TEMPLATE = PROJECT_ROOT / "templates" / "plan-template.md"
+
+HAS_PWSH = shutil.which("pwsh") is not None
+_POWERSHELL = shutil.which("powershell.exe") or shutil.which("powershell")
+
+
+def _install_bash_scripts(repo: Path) -> None:
+ d = repo / ".specify" / "scripts" / "bash"
+ d.mkdir(parents=True, exist_ok=True)
+ shutil.copy(COMMON_SH, d / "common.sh")
+ shutil.copy(SETUP_PLAN_SH, d / "setup-plan.sh")
+
+
+def _install_ps_scripts(repo: Path) -> None:
+ d = repo / ".specify" / "scripts" / "powershell"
+ d.mkdir(parents=True, exist_ok=True)
+ shutil.copy(COMMON_PS, d / "common.ps1")
+ shutil.copy(SETUP_PLAN_PS, d / "setup-plan.ps1")
+
+
+def _minimal_templates(repo: Path) -> None:
+ tdir = repo / ".specify" / "templates"
+ tdir.mkdir(parents=True, exist_ok=True)
+ shutil.copy(PLAN_TEMPLATE, tdir / "plan-template.md")
+
+
+def _clean_env() -> dict[str, str]:
+ """Return a copy of the current environment with any SPECIFY_* vars removed.
+
+ setup-plan.{sh,ps1} honors SPECIFY_FEATURE, SPECIFY_FEATURE_DIRECTORY, etc.,
+ which would otherwise leak from a developer shell or CI runner and make these
+ tests flaky. Stripping them forces every case to rely purely on git branch +
+ .specify/feature.json state set up by the fixture.
+ """
+ env = os.environ.copy()
+ for key in list(env):
+ if key.startswith("SPECIFY_"):
+ env.pop(key)
+ return env
+
+
+def _git_init(repo: Path) -> None:
+ subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+ subprocess.run(
+ ["git", "config", "user.email", "[email protected]"], cwd=repo, check=True
+ )
+ subprocess.run(["git", "config", "user.name", "Test User"], cwd=repo, check=True)
+ subprocess.run(
+ ["git", "commit", "--allow-empty", "-m", "init", "-q"], cwd=repo, check=True
+ )
+
+
+def plan_repo(tmp_path: Path) -> Path:
+ repo = tmp_path / "proj"
+ repo.mkdir()
+ _git_init(repo)
+ (repo / ".specify").mkdir()
+ _minimal_templates(repo)
+ _install_bash_scripts(repo)
+ _install_ps_scripts(repo)
+ return repo
+
+
+@requires_bash
+def test_setup_plan_passes_custom_branch_when_feature_json_valid(plan_repo: Path) -> None:
+ subprocess.run(
+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],
+ cwd=plan_repo,
+ check=True,
+ )
+ feat = plan_repo / "specs" / "001-tiny-notes-app"
+ feat.mkdir(parents=True)
+ (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
+ (plan_repo / ".specify" / "feature.json").write_text(
+ json.dumps({"feature_directory": "specs/001-tiny-notes-app"}),
+ encoding="utf-8",
+ )
+ script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
+ result = subprocess.run(
+ ["bash", str(script)],
+ cwd=plan_repo,
+ capture_output=True,
+ text=True,
+ check=False,
+ env=_clean_env(),
+ )
+ assert result.returncode == 0, result.stderr + result.stdout
+ assert (feat / "plan.md").is_file()
+
+
+@requires_bash
+def test_setup_plan_fails_custom_branch_without_feature_json(plan_repo: Path) -> None:
+ subprocess.run(
+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],
+ cwd=plan_repo,
+ check=True,
+ )
+ script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
+ result = subprocess.run(
+ ["bash", str(script)],
+ cwd=plan_repo,
+ capture_output=True,
+ text=True,
+ check=False,
+ env=_clean_env(),
+ )
+ assert result.returncode != 0
+ assert "Not on a feature branch" in result.stderr
+
+
+@requires_bash
+def test_setup_plan_numbered_branch_unchanged_without_feature_json(
+ plan_repo: Path,
+) -> None:
+ subprocess.run(
+ ["git", "checkout", "-q", "-b", "001-tiny-notes-app"],
+ cwd=plan_repo,
+ check=True,
+ )
+ feat = plan_repo / "specs" / "001-tiny-notes-app"
+ feat.mkdir(parents=True)
+ (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
+ script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
+ result = subprocess.run(
+ ["bash", str(script)],
+ cwd=plan_repo,
+ capture_output=True,
+ text=True,
+ check=False,
+ env=_clean_env(),
+ )
+ assert result.returncode == 0, result.stderr + result.stdout
+ assert (feat / "plan.md").is_file()
+
+
[email protected](not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_setup_plan_ps_passes_custom_branch_when_feature_json_valid(plan_repo: Path) -> None:
+ subprocess.run(
+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],
+ cwd=plan_repo,
+ check=True,
+ )
+ feat = plan_repo / "specs" / "001-tiny-notes-app"
+ feat.mkdir(parents=True)
+ (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
+ (plan_repo / ".specify" / "feature.json").write_text(
+ json.dumps({"feature_directory": "specs/001-tiny-notes-app"}),
+ encoding="utf-8",
+ )
+ script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"
+ exe = "pwsh" if HAS_PWSH else _POWERSHELL
+ result = subprocess.run(
+ [exe, "-NoProfile", "-File", str(script)],
+ cwd=plan_repo,
+ capture_output=True,
+ text=True,
+ check=False,
+ env=_clean_env(),
+ )
+ assert result.returncode == 0, result.stderr + result.stdout
+ assert (feat / "plan.md").is_file()
+
+
[email protected](not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_setup_plan_ps_fails_custom_branch_without_feature_json(
+ plan_repo: Path,
+) -> None:
+ subprocess.run(
+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],
+ cwd=plan_repo,
+ check=True,
+ )
+ script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"
+ exe = "pwsh" if HAS_PWSH else _POWERSHELL
+ result = subprocess.run(
+ [exe, "-NoProfile", "-File", str(script)],
+ cwd=plan_repo,
+ capture_output=True,
+ text=True,
+ check=False,
+ env=_clean_env(),
+ )
+ assert result.returncode != 0
+ assert "Not on a feature branch" in result.stderr