fix(scripts): name setup-plan's feature directory key FEATURE_DIR

[Yash-Chindam]

Fixes #4017

Problem

setup-plan emitted a JSON key named SPECS_DIR holding $FEATURE_DIR — the per-feature subdirectory, not the specs root.

The name is already in use elsewhere with the other meaning. In scripts/bash/create-new-feature.sh:

SPECS_DIR="$REPO_ROOT/specs"           # the specs root
FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"  # one feature inside it

So SPECS_DIR meant specs/ in one script and specs/001-my-feature/ in another.

Why FEATURE_DIR is the right name

setup-plan was the only script in the suite using SPECS_DIR. Every sibling already emits FEATURE_DIR for exactly this value:

scripts/bash/setup-tasks.sh:75           FEATURE_DIR:$feature_dir
scripts/bash/check-prerequisites.sh:122  FEATURE_DIR:$feature_dir
scripts/bash/check-prerequisites.sh:208  FEATURE_DIR:$feature_dir

This brings setup-plan in line rather than inventing a convention.

Scope

The issue lists four bash locations. The same key is emitted by all three ports, and there is a consumer that parses it by name — fixing only bash would leave the ports disagreeing, which is worse than the current state. Full surface:

scripts/bash/setup-plan.sh         73, 75, 77, 83
scripts/powershell/setup-plan.ps1  79, 86
scripts/python/setup_plan.py       85, 93
templates/commands/plan.md         62   <- parses the key by name

plan.md ships alongside the scripts, so it stays in sync automatically.

On the compatibility question

I raised rename-vs-deprecated-alias on the issue. Going with the straight rename here, since plan.md is the only in-repo consumer and the value was never the specs root — anything relying on SPECS_DIR to mean the specs root was already reading the wrong path. Happy to switch to emitting FEATURE_DIR while keeping SPECS_DIR as a deprecated alias for a release or two if you would rather not break external parsers.

Verification

Ran all three variants against a scratch project and compared the emitted keys:

bash    rc=0 keys=['BRANCH', 'FEATURE_DIR', 'FEATURE_SPEC', 'IMPL_PLAN']
python  rc=0 keys=['BRANCH', 'FEATURE_DIR', 'FEATURE_SPEC', 'IMPL_PLAN']
pwsh    rc=0 keys=['BRANCH', 'FEATURE_DIR', 'FEATURE_SPEC', 'IMPL_PLAN']

Also confirmed no other reference to the old key remains outside create-new-feature.sh, where SPECS_DIR correctly means the specs root and is untouched.

pytest tests/ -k "plan or command_template or preset" — 852 passed. The 8 failures are all WinError 1314: A required privilege is not held by the client from symlink creation; the identical set fails on unmodified upstream/main, so they are environmental and unrelated.

---

Disclosure: this change was developed with AI assistance (Claude). The AI helped map the affected call sites across the three ports, apply the rename, and draft this description. The three-port key comparison above was produced by running the scripts; I reviewed the change before submitting.

[Copilot]

🟡 Changes recommended

The corrected output contract lacks an explicit regression test that would prevent all ports from reverting consistently.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Aligns setup-plan outputs with the repository-wide FEATURE_DIR naming convention.

Changes:

• Renames SPECS_DIR to FEATURE_DIR across all script variants.
• Updates the plan command’s JSON parsing instructions.

File summaries

File	Description
templates/commands/plan.md	Uses the renamed output key.
scripts/python/setup_plan.py	Renames Python JSON and text outputs.
scripts/powershell/setup-plan.ps1	Renames PowerShell outputs.
scripts/bash/setup-plan.sh	Renames Bash outputs, including both JSON paths.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mnriem]

Please address Copilot feedback

[Yash-Chindam]

Addressed in the latest push — good catch, and the criticism was accurate: every existing setup-plan test compares the ports against each other, so all three could have regressed to SPECS_DIR together and still gone green.

test_all_variants_emit_feature_dir_not_specs_dir now pins the contract absolutely, parametrised over JSON and text mode and covering bash, Python and PowerShell:

• SPECS_DIR absent from stdout
• JSON keys exactly ['BRANCH', 'FEATURE_DIR', 'FEATURE_SPEC', 'IMPL_PLAN']
• text mode carries a FEATURE_DIR: line
• the value is the feature directory, not the specs root

One wrinkle worth flagging: the value is matched by suffix rather than by full path. The ports legitimately disagree on path flavour — under MSYS, bash reports /tmp/.../specs/001-my-feature where the Python and PowerShell ports report C:\...\specs\001-my-feature. An equality assertion would have passed locally on Linux and failed the Windows matrix. The suffix comparison still separates specs/001-my-feature from a bare specs, which is the regression actually being guarded; I checked it rejects both /tmp/proj/specs and C:\proj\specs.

Verified all six port × mode combinations produce the expected key and value.

Also rebased onto current main.

Disclosure: AI assistance (Claude) was used for this change and comment, as with the original PR.