Shell scripts: paths-only validates branch and setup-plan can overwrite plan.md

[flamerged]

I found two shell-script behaviors in current main at 51e6a14 while vendoring Spec Kit into a repo and testing the generated Claude integration.

1. check-prerequisites.sh --paths-only still validates branch name

The help text says --paths-only should output path variables with no prerequisite validation. The Claude /speckit-clarify skill also calls:

.specify/scripts/bash/check-prerequisites.sh --json --paths-only

But check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" runs before the PATHS_ONLY early exit. In a normal non-Spec branch, --paths-only can fail before returning paths.

Suggested fix: move branch validation after the PATHS_ONLY block.

2. setup-plan.sh overwrites existing plan.md

setup-plan.sh unconditionally copies the plan template to $IMPL_PLAN:

cp "$TEMPLATE" "$IMPL_PLAN"

On reruns this can overwrite an already authored implementation plan.

Suggested fix: only copy/touch when $IMPL_PLAN does not exist, unless an explicit force mode is added. Also send status messages to stderr in --json mode so stdout remains parseable JSON.

I tested equivalent local patches in a temp Spec Kit directory:

• check-prerequisites.sh --json --paths-only returns JSON on a normal branch.
• setup-plan.sh --json preserves an existing plan.md.
• setup-plan.sh --json creates a missing plan.md and still emits parseable JSON.

[bixu]

Confirming this reproduces on current main: re-running /speckit-plan on a feature that already has a hand-authored plan.md silently replaces without warning.

The trigger in practice is the common "spec changed, re-plan" loop: run /speckit-clarify to record a decision, then /speckit-plan to propagate it — at which point the populated plan is lost. That overlaps with the workflow concern in #1059.

The suggested guard here (only cp when $IMPL_PLAN is absent, or behind an explicit --force) would prevent the data loss. Recovery via git checkout HEAD -- plan.md works, but only if the prior plan was already committed.

[janwillemkeizer]

Bumping on this thread because there's a related gap that I think is worth deciding on before any of the three open PRs (#2481, #2571, #2672) land — to avoid landing the narrow fix and then immediately revisiting the same code.

The narrower fix doesn't cover non–--paths-only callers

The three open PRs all move check_feature_branch below the --paths-only early exit. That unblocks the documented --paths-only contract (which is what #2477 / #2653 #1 are strictly about), but it leaves a related case still broken:

When a project uses .specify/feature.json to decouple the feature directory from the branch name (the mechanism introduced for /speckit.plan in the now-merged #2349), commands that invoke check-prerequisites.sh without --paths-only — e.g. /speckit.implement, /speckit.analyze — still fail with the "Not on a feature branch" error on any branch that doesn't match ^[0-9]{3,}- or the timestamp pattern. The full-validation path doesn't consult feature.json at all.

Precedent: PR #2349 already established the bypass pattern

setup-plan.sh:36-37 and setup-tasks.sh:32-33 use:

if ! feature_json_matches_feature_dir "$REPO_ROOT" "$FEATURE_DIR"; then
    check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
fi

The same one-line change in check-prerequisites.sh:85 would make the three scripts consistent and would cover both the --paths-only case in this issue and the full-validation case for /speckit.implement etc.

Proposed scope decision

I see three reasonable options and would value a maintainer steer before anyone (including me) opens a fourth PR:

1. Land the narrower paths-only fix as-is (fix: move branch validation after --paths-only exit #2481/Fix paths-only validation in check-prerequisites #2571/fix: paths-only skips branch validation, setup-plan preserves existing plan #2672) and treat the full-validation gap as a separate follow-up issue. Cleanest review story, but means two round-trips on the same file.
2. Expand one of the open PRs to use feature_json_matches_feature_dir as the bypass instead of moving the call below the early exit. That fixes both cases with a single edit and matches the precedent from fix(plan): use .specify/feature.json to allow /speckit.plan on custom git branches (#2305) #2349.
3. Keep them separate but sequence them: merge the paths-only fix first, then take a small follow-up PR that adds the feature.json bypass for the non-paths-only branches.

My preference is (2) for symmetry with setup-plan.sh / setup-tasks.sh, but I don't want to step on the existing PRs without your nod.

If (2) or (3) is acceptable, I'm happy to send a PR with a manual test report (/speckit.implement and --paths-only both on a non-feature branch with feature.json pointing at an existing spec dir) plus the agent-config-consistency test.

---

AI disclosure: this comment was drafted with Claude Code (Anthropic) after a manual investigation of check-prerequisites.sh, common.sh, the merged PR #2349, and the three open PRs. The reasoning, scope analysis, and recommendation are mine; the prose is AI-assisted.

[mnriem]

Thank you!