Why
Running specflow init --here on a directory that already contains specflow-managed files (e.g. a Vite project where a previous partial init left .claude/ behind) exits with an error message that is both stale (hardcodes "v0.1" even on v0.6.x) and unhelpful — it does not tell the user what options they have. This is the first-touch experience for any brownfield project, so the friction is disproportionate to the actual problem.
Two fixes are bundled here: a copy fix (remove the hardcoded version string) and a UX fix (make the error message actionable so users know to run --force or specflow upgrade).
Acceptance criteria
- The stale string
"Specflow v0.1 does not yet support upgrading an existing project." is removed from src/cli/handlers/init_handler.ts.
- The replacement message is version-agnostic and includes both escape hatches:
specflow init --here --force — re-initialises in place, backs up existing files to .specflow.bak
specflow upgrade — incremental update if a .specflow/installed.lock already exists
- The message is printed to stderr (unchanged from current behaviour).
- Exit code remains
3 for this conflict path (no behaviour regression).
- The conflict file list is still printed so the user knows which files are affected.
- A unit/integration test covers the conflict-path output for the
--here flag (or updates an existing one if it already asserts on that string).
Out of scope
- Automatically delegating
init --here to specflow upgrade — that would require init to read the lock, resolve the harness, and call the upgrade use case; it is a separate, more invasive change and should be its own ticket if Kevin wants it.
- Changing the
--force behaviour itself (backup logic, overwrite semantics) — already correct.
- Adding a
--force flag to specflow upgrade (already exists).
- Any change to the
specflow upgrade error path ("no .specflow/installed.lock found") — out of scope.
Notes
- Stale string lives at
src/cli/handlers/init_handler.ts line 61–63.
upgrade_project.ts already emits its own guidance ("Run specflow init --here --force to enable upgrades") — the new init error message should be consistent with that phrasing.
- No dependency on other open issues.
- Low complexity: copy change + one test update. No domain logic touched.
Why
Running
specflow init --hereon a directory that already contains specflow-managed files (e.g. a Vite project where a previous partial init left.claude/behind) exits with an error message that is both stale (hardcodes "v0.1" even on v0.6.x) and unhelpful — it does not tell the user what options they have. This is the first-touch experience for any brownfield project, so the friction is disproportionate to the actual problem.Two fixes are bundled here: a copy fix (remove the hardcoded version string) and a UX fix (make the error message actionable so users know to run
--forceorspecflow upgrade).Acceptance criteria
"Specflow v0.1 does not yet support upgrading an existing project."is removed fromsrc/cli/handlers/init_handler.ts.specflow init --here --force— re-initialises in place, backs up existing files to.specflow.bakspecflow upgrade— incremental update if a.specflow/installed.lockalready exists3for this conflict path (no behaviour regression).--hereflag (or updates an existing one if it already asserts on that string).Out of scope
init --heretospecflow upgrade— that would require init to read the lock, resolve the harness, and call the upgrade use case; it is a separate, more invasive change and should be its own ticket if Kevin wants it.--forcebehaviour itself (backup logic, overwrite semantics) — already correct.--forceflag tospecflow upgrade(already exists).specflow upgradeerror path ("no .specflow/installed.lock found") — out of scope.Notes
src/cli/handlers/init_handler.tsline 61–63.upgrade_project.tsalready emits its own guidance ("Run specflow init --here --force to enable upgrades") — the new init error message should be consistent with that phrasing.