[Bug]: custom branch from spec creation is not respected on directory creation and future steps

[PeterDaumQS]

Bug Description

When running /speckit.specify with a custom branch name (eg feature/PRO123-test-branch), the directory is created based on the chosen strategy (eg 001-test-branch).
And starting a new session for /speckit.plan ignores the given custom branch and creates a new one based on the directory.

Steps to Reproduce

1. /speckit.specify The branch is "feature/my-feature-branch". The requirements are .....
2. Start a new context session
3. /speckit.plan Here are some hints ...

Expected Behavior

The expected behavior is, that /speckit.specify creates also the directory based on the branch name and further sessions use the given custom branch name continously.

Actual Behavior

/speckit.specify obeys the given custom branch, creates it and switches to it. But the spec directory nevertheless is setup based on the chose strategy.

In a new session using /speckit.plan ignores the custom branch name (stated in the spec file) and creates a new branch

Specify CLI Version

0.7.1.dev0

AI Agent

GitHub Copilot

Operating System

Ubuntu 24.04.3 LTS

Python Version

Python 3.12.3

Error Logs

None

Additional Context

No response

[mnriem]

Can you please upgrade to the latest version and validate if it is still an issue?

[Adr1an04]

I tested this on the latest checkout and I’m still seeing an issue here.

From what I can tell, the spec directory and git branch are intentionally separate on current main, so I don’t think the directory naming itself is the bug anymore.

The part that still seems off is that /speckit.plan can reject a custom branch like feature/my-feature-branch even when the feature directory was already fixed correctly.

I’m taking a closer look at that now to understand it more.

[PeterDaumQS]

Can confirm it's not working yet.

Wouldn't it be better to enhance the feature.json with both directory and branch name, so no guessing is needed on latter steps?

Reasoning is, that it doesn't matter for the latter steps how the branch and the directory is named, as long as the information for the current feature can be obtained. Or do I overlook something here?

[Adr1an04]

Yeah that makes sense to me.

Were you thinking the right fix here is to persist both the directory and branch in feature.json, or just that it would be a cleaner direction in general?

Happy to help out with either direction though.

[PeterDaumQS]

Considering that some repose do not use git, the feature.json is fine as it is right now for the non-git projects.

When working in parallel with multiple developers on the same git enabled project, the file can be become a burden, when it's checked in, as it may lead to merge conflicts - if I'm not mistaken -.

May be for the projects backed by git, the feature json shouldn't be used, but rather the feature branch shall be the source of truth for the resolution of the spec directory. And any checking if it matches an expected pattern can be removed.

This would match the default situation for branch numbering (sequential and timestamp) and also when both, the SPECIFY_FEATURE_DIRECTORY and GIT_BRANCH_NAME are set equally.

And also allows either a single developer to run implementations in parallel with worktrees and/or multiple developers to do the same without the risk of merge conflicts on a feature local configuration file.

What do you think?

[Adr1an04]

Yeah, I get what you mean with the merge conflicts. But in my opinion switching the resolution model over to branch as source of truth feels like a bigger design change though no?

I think keeping this PR focused on fixing the custom branch bug first, and leaving the branch vs feature.json question for another issue would be better personally.

[PeterDaumQS]

Yeah you're right, that would be a follow up topic - I'll create an improvement issue for this latter this day.

When focusing on the fix, I would prefer to enhance the feature.json. It is already present and can be extended to solve the lookup topic easily.

Other ways I can think of would introduce bigger changes and more logic for look ups etc. I guess.

[Adr1an04]

Yeah, that sounds more reasonable to me.

If you’re already picking that up, I’d be happy to help with testing or review!

[PeterDaumQS]

Haven't started it yet, but would be happy to contribute

[mnriem]

Thank you all for considering helping out with the identified issue. It is correct that Git branch creation and spec directory creation have been separated on purpose. Please keep in mind that this was intentional and at a future release automatic Git branching will be an opt-in instead of an opt-out

[Adr1an04]

Thank you I appreciate the clarification. I’m still trying to learn the repo as much as I can so I can contribute in the right way, so that context is really helpful!