How to cleanly end a feature branch?

[youngjoel]

$speckit.specify updates .specify/feature.json but as far as I can tell, nothing clears it. When I end a feature branch (which has to be done manually -- no skill/command to help), the feature.json file still points to the old branch, resulting sometimes in artifacts getting changed in the specs/{{feature_directory}}/ path.

1. What is the "right" way to clear the feature_directory during my manual feature_branch close/merge process?
2. Should there be a helper skill with hooks that can do a local/github/gitlab merge w/ squash etc., that things like the "archive" extension could hook into to automatically archive the feature spec/plan into master etc.?

[mnriem]

Good questions — and there's a recent change worth knowing about.

1. What feature.json actually is / how to "clear" it

.specify/feature.json is just a per-checkout current-feature pointer. Resolution order is SPECIFY_FEATURE_DIRECTORY env var → .specify/feature.json → error. Nothing clears it on branch switch by design — it's meant to be overwritten, not reset. To re-point it when you start your next piece of work:

• Run /speckit.specify for the new feature — it rewrites feature.json to the new dir. This is the normal path.
• Or just delete .specify/feature.json; it's regenerated on the next specify run.
• Or set SPECIFY_FEATURE_DIRECTORY for a one-off (it re-persists on use).

So the "stale pointer changing artifacts in the old specs/… dir" happens when a downstream command runs before you've re-pointed. The fix is to re-run /speckit.specify (or clear the file) when you switch, rather than looking for a close command that resets it.

2. It shouldn't be committed in the first place — and now it isn't

A big part of the pain here was feature.json being tracked, so it followed branches and created churn/merge noise. As of #4000 (merged), specify init scaffolds a managed .specify/.gitignore that ignores feature.json (and extensions/*/local-config.yml). Going forward it's treated as machine/session-local: it won't be committed, and a merge won't drop a stale pointer into main.

Two caveats:

• A .gitignore doesn't untrack a file already committed. If your repo committed feature.json before this, run a one-time git rm --cached .specify/feature.json.
• This only changes git tracking. It does not auto-clear the local pointer on branch close — you still re-point locally as in (1).

3. A merge/squash + archive helper skill

There's no bundled skill for this today (no "archive" extension yet). It's a reasonable feature request — the extension + manifest model could support a close/merge hook that squashes and archives the spec/plan — but it'd need to be designed. If you want to pursue it, opening a separate feature-request issue with the desired flow (local vs GitHub/GitLab merge, squash, where the archived spec lands) would be the way to move it forward.

---

Co-authored by @mnriem and GitHub Copilot (model: Claude Opus 4.8) — drafted by the agent and reviewed before posting.