[Bug]: check-prerequisites.sh --paths-only still runs branch validation, contradicting --help

Open Beginner friendly
#2,477 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
86/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
bash, git, powershell
Domain
cli, tooling

Research direction

Start with scripts/bash/check-prerequisites.sh and the --paths-only flow described in the issue, then compare its ordering with scripts/powershell/check-prerequisites.ps1 and the branch check in common.sh. Reproduce on a non-feature branch with --paths-only and --json; done means path variables are emitted and the command succeeds without branch validation.

Written by the indexing model from the issue text.

Description

stale

Bug Description

scripts/bash/check-prerequisites.sh --paths-only is documented as "no validation" / "no prerequisite validation", but the script runs check_feature_branch before the --paths-only early exit. The result: when the current branch does not match the feature-branch naming convention, --paths-only exits non-zero with a branch-format error, even though the caller asked for paths only and explicitly opted out of validation.

Source: https://github.com/github/spec-kit/blob/main/scripts/bash/check-prerequisites.sh#L81-L113

# Get feature paths and validate branch
_paths_output=$(get_feature_paths) || { ... ; exit 1; }
eval "$_paths_output"
unset _paths_output
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1   # ← runs even with --paths-only

# If paths-only mode, output paths and exit (support JSON + paths-only combined)
if \$PATHS_ONLY; then
    ...
    exit 0
fi

The header documentation (line 14) says: `--paths-only Only output path variables (no validation)` and `--help` (line 54) says `(no prerequisite validation)`. Branch validation is the most user-visible form of validation, so this contradicts the documented behavior.

Steps to Reproduce

  1. Initialize a Spec Kit project: `specify init test-paths-only --integration claude`
  2. Switch to a non-feature branch: `git checkout -b chore/some-cleanup`
  3. Run paths-only: `./.specify/scripts/bash/check-prerequisites.sh --paths-only`

Expected Behavior

`--paths-only` succeeds and emits `REPO_ROOT`, `BRANCH`, `FEATURE_DIR`, etc., regardless of branch name (the caller asked for paths, not validation).

Actual Behavior

Exit 1 with branch-validation error (the message produced by `check_feature_branch` in `common.sh`), no path variables emitted.

Specify CLI Version

0.7.4.dev0

AI Agent

Claude Code

Suggested Fix

Move `check_feature_branch` after the `if $PATHS_ONLY; then ... exit 0; fi` block so `--paths-only` truly skips validation. Same source ordering already exists in `scripts/powershell/check-prerequisites.ps1` — please verify both are aligned.

Context

Surfaced while bulk-installing Spec Kit across 20 internal projects. `/speckit-tasks` and similar commands invoke `check-prerequisites.sh --paths-only --json` from non-feature chore branches and unexpectedly fail with branch-format errors despite the documented opt-out.

Dominant language
Python
Stars
138k
Forks
12.4k
Avg merge
3d 6h
Merged PRs (30d)
136

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/spec-kit

All issues in github/spec-kit

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.