Repository navigation
[Bug]: Missing plan template creates a zero-byte plan.md and reports success #4961
Description
Bug Description
PowerShell plan setup creates an empty plan.md and exits successfully when no plan template resolves. Prerequisite checks accept that empty file, and restoring the template then rerunning setup does not initialize it.
Steps to Reproduce
- In an isolated project, copy the checkout's
common.ps1,setup-plan.ps1, andcheck-prerequisites.ps1into.specify\scripts\powershell. - Create
.specify\feature.jsoncontaining{"feature_directory":"specs/001-repro"}, create that feature directory and a nonemptyspec.md, and leave all plan-template sources absent. - From the fixture root, run
pwsh -NoProfile -NonInteractive -File .\.specify\scripts\powershell\setup-plan.ps1 -Json. Inspect the exit code andplan.mdsize. - Run
pwsh -NoProfile -NonInteractive -File .\.specify\scripts\powershell\check-prerequisites.ps1 -Json -RequireSpec. - Copy the checkout's
templates\plan-template.mdinto the fixture's.specify\templates\plan-template.mdand rerun setup and prerequisites.
Run with inherited SPECIFY_* environment variables cleared so feature resolution uses the fixture's state rather than another project.
Expected Behavior
Missing required plan template should cause setup to fail with an actionable diagnostic, without creating an unusable empty plan. Prerequisites should not treat an empty plan as ready for downstream work.
Actual Behavior
Missing-template setup exits 0, emits Warning: Plan template not found on stderr, returns valid path JSON, and creates a zero-byte plan.md. Prerequisites exit 0.
After restoring the template, setup exits 0 and reports skipping template copy; plan.md remains zero bytes and prerequisites still exit 0.
The missing-template case also succeeds in text mode; its warning goes to stdout instead of stderr.
Specify CLI Version
1.1.4
AI Agent
Alquimia AI
Operating System
Windows; PowerShell 7.6.7
Python Version
Python 3.11.5 (reproduction harness)
Error Logs
Missing template:
stderr: Warning: Plan template not found
exit code: 0
plan.md size: 0 bytes
Prerequisites with empty plan (-Json -RequireSpec):
exit code: 0
Restored template, setup rerun:
stderr: Plan already exists at <fixture>\specs\001-repro\plan.md, skipping template copy
exit code: 0
plan.md size: 0 bytes
Prerequisites after template restoration:
exit code: 0Additional Context
No response
AI Disclosure
GitHub Copilot, powered by GPT-6.1 Sol
Activity
github-actions commentedon Oct 14, 2026
Bug assessment — missing-plan-template: Valid · severity medium
Bug Assessment: Missing plan template creates a zero-byte plan.md and reports success
Report (summarized)
The reporter observes that, on Windows with PowerShell 7.6.7 and Specify CLI 1.1.4, running the installed PowerShell
setup-plan.ps1 -Jsonwith no resolvable plan template exits successfully, emits a warning, returns path JSON, and creates a zero-byteplan.md.check-prerequisites.ps1 -Json -RequireSpecthen accepts that file. Restoring the template and rerunning setup does not repair the file because setup treats the existing empty file as a valid plan. The report also notes the missing-template text-mode warning is written to stdout.No additional comments supplied reproduction context.
Symptom
When
plan-template.mdcannot be resolved, PowerShell setup reports success and materializes an empty plan file instead of failing without creating an unusable artifact. Because prerequisite validation checks only whetherplan.mdexists, downstream workflow steps proceed as though a usable plan is present; later template restoration is ineffective because the existing empty file is skipped.Reproduction
common.ps1,setup-plan.ps1, andcheck-prerequisites.ps1into an isolated fixture's.specify\scripts\powershelldirectory..specify\feature.jsonpointing tospecs/001-repro, create that feature directory with a nonemptyspec.md, and leave all plan-template sources absent.pwsh -NoProfile -NonInteractive -File .\.specify\scripts\powershell\setup-plan.ps1 -Json; observe exit code 0 and a zero-byteplan.md.check-prerequisites.ps1 -Json -RequireSpec; observe exit code 0..specify\templates\plan-template.mdand rerun setup; observe that the existing empty plan is skipped and remains zero bytes.The report states that inherited
SPECIFY_*variables were cleared. The exact fixture and command output are from the issue report.Suspected Code Paths
scripts/powershell/setup-plan.ps1:41-67— checks only whetherIMPL_PLANis a leaf file; when template resolution returns$null, printsWarning: Plan template not found, creates the file withNew-Item, and continues to the success JSON output.scripts/powershell/setup-plan.ps1:42-47— on subsequent runs, any existingplan.md, including zero bytes, takes the skip path, so a later template restoration cannot initialize it.scripts/powershell/check-prerequisites.ps1:103-109— validatesIMPL_PLANwithTest-Path ... -PathType Leaf, which accepts an empty file and does not validate nonzero content.scripts/powershell/common.ps1:532-600—Resolve-TemplateContentis the template-resolution boundary and returns$nullwhen no valid template source is found.scripts/bash/setup-plan.sh:45-63andscripts/python/setup_plan.py:68-72— the same empty-file fallback exists in the Bash and Python ports, indicating this is a cross-port behavior gap rather than only a PowerShell implementation detail.tests/test_setup_plan_python_parity.py:125-143— current parity coverage explicitly expects missing-template setup to return 0 and create an empty plan, so it would need to change with the intended behavior.tests/test_setup_plan_no_overwrite.py:258-285— current PowerShell coverage expects a missing-template warning but also a successful run, leaving the failure case untested.Root Cause Hypothesis
Confidence: high. The setup contract treats template absence as a recoverable warning: PowerShell explicitly calls
New-Item -ItemType Fileafter a null template result, while prerequisite checks define readiness as file existence only. The existing-file guard then makes the empty placeholder durable. The Bash and Python ports implement the same fallback (touch/touch()), so parity tests have institutionalized the behavior.Proposed Remediation
Preferred: Treat inability to resolve the required
plan-templateas a setup error. In all three setup implementations, emit an actionable diagnostic to stderr, remove any partially created output if necessary, return a nonzero exit code, and do not createplan.md. Preserve the existing-plan behavior for a nonempty user-authored file. Add a content/readiness check to prerequisite validation so an emptyplan.mdis rejected (with a clear remediation message), or ensure setup is the only producer and reject zero-byte files there as well. The error and stream behavior should remain consistent between JSON and text modes: stdout must stay reserved for the documented JSON payload in JSON mode.A compatibility-conscious variant can recognize an existing zero-byte
plan.mdas an incomplete setup artifact, replace it only when a template is now resolvable, and fail otherwise. This repairs the reported restoration scenario but risks overwriting a deliberately empty user file; the preferred approach avoids treating empty files as valid and requires explicit user action for ambiguous existing files.Files likely to change:
scripts/powershell/setup-plan.ps1scripts/bash/setup-plan.shscripts/python/setup_plan.pyscripts/powershell/check-prerequisites.ps1scripts/bash/check-prerequisites.shscripts/python/check_prerequisites.pytests/test_setup_plan_python_parity.pytests/test_setup_plan_no_overwrite.pytests/test_check_prerequisites_python_parity.pyTests to add or update:
plan-templatereturns nonzero, writes noplan.md, and emits the same actionable error in JSON and text modes with JSON stdout remaining parseable where applicable.-RequireSpec/equivalent flows.Risks & Considerations
Open Questions
plan.mdalways be treated as invalid, or should setup repair it automatically when a template becomes available?]Fix missing-plan-template: reject empty plan setup
github-actions commentedon Oct 14, 2026
Pull request created: #4962
github-actions commentedon Oct 14, 2026
Draft PR #4962 proposes the
missing-plan-templatefix: setup now fails without creatingplan.mdwhen the template is missing, and prerequisite checks reject zero-byte plans. Please review the draft and validate the fix in the stage-3bug-testworkflow if configured.github-actions commentedon Oct 14, 2026
Bug test — missing-plan-template:⚠️ inconclusive · 0 passed, 0 failed, 0 skipped · fix from PR #4962 (head
9c7cc2221231913023ed6fd8b7bf4dc734b42900)Bug Test Report: Missing plan template creates an empty plan
9c7cc2221231913023ed6fd8b7bf4dc734b42900uv sync --extra test && timeout 600 uv run pytest tests/test_setup_plan_python_parity.py tests/test_setup_plan_no_overwrite.py tests/test_check_prerequisites_python_parity.py -qSummary
The proposed fix was checked out at the PR head, and the repository's focused regression tests were identified. The test run could not start because the runner denied permission for dependency setup and test-process execution before either command produced test results; therefore this run provides no pass/fail evidence for the fix.
Test Results
Failures (if any)
None. The run was blocked during environment/test-process setup rather than by an assertion failure.
Verification vs. Historical Fix
Not applicable (no historical fix referenced in the issue or assessment).
Notes & Caveats
9c7cc2221231913023ed6fd8b7bf4dc734b42900.testoptional dependency group inpyproject.toml; the focused tests are the three files named by the bug-fix assessment and PR.uv sync --extra testwas attempted first, but the runner returned a permission-denied result before dependency setup could execute. A direct timed pytest invocation was also blocked by the runner, so no test counts or duration can be inferred.[bug-fix] Fix missing-plan-template: reject empty plan setup (#4962)