[Feature Request] Configurable naming convention for /specify branch and specs/ folder

[jmrtnz94]

Please add a way to configure the naming convention used when /specify creates a Git branch and the corresponding specs/<…> folder. Many teams need names that include ticket IDs or follow GitFlow-style prefixes.

Current behavior
/specify auto-creates a branch (e.g., 003-chat-system) and a matching directory under specs/…. The names are not user-configurable.

Requirement (behavioral)
Whatever approach we choose, the branch name and folder name should always stay in sync. A single computed value should be used to create both.

⸻

Approaches (seeking maintainer preference)

Kept in the repo’s style (simple CLI, optional config under .specify/):
1. One-off CLI flags (explicit, easy to trial)
• specify --branch-format ""
• Folder path derived as specs/{branch} by default
• (Optional) --folder-format "" so long as it includes {branch} (to guarantee sync)
2. Repo-wide config (opt-in)
• .specify/config.toml (or .specify/config.json)
• Example:

[naming]
branch_format = "feature/{ticket}-{kebab(summary)}" # e.g., feature/PROJ-123-sync-webhooks
folder_format = "specs/{branch}" # keeps folder in lockstep with branch

Optional validation:

validate_branch = "^(feature|bugfix|hotfix)/[A-Z]+-\d+-[a-z0-9-]+$"

•	Minimal token set (practical and easy to document):
•	{seq} (zero-padded sequence like 003)
•	{summary} / {kebab(summary)}
•	{ticket} (via --ticket PROJ-123 or inferred by regex)
•	{date} (YYYYMMDD)

3.	Environment variables (handy in CI)
•	SPECIFY_BRANCH_FORMAT, SPECIFY_FOLDER_FORMAT

Precedence (suggested): flag > env > config > default.

⸻

Back-compat & safety
• If no flags/env/config are provided, behavior remains exactly as today.
• Optional validate_branch lets teams enforce a regex and fail fast with a clear error.
• Sensible sanitization (lowercase, spaces → -, strip illegal chars).

⸻

Questions for maintainers
• Which interface would you prefer we implement first: flags, config, or both with precedence?
• TOML vs JSON for .specify/?
• Keep folder strictly derived as specs/{branch} (simplest sync), or allow a folder_format as long as it includes {branch}?
• Are the proposed tokens sufficient for v1?

⸻

Implementation plan (I’m happy to do this after your feedback)
1. Finalize interface (flags/config/env + precedence).
2. Add small templating utility (tokens + sanitization).
3. Wire naming into /specify so a single computed name drives both branch and folder creation.
4. Add optional regex validation.
5. Tests + README examples (Jira/GitFlow/sequence).

If this direction looks good, I can open a PR and iterate based on your guidance.

[benoitheinrich]

Hi, I'd be very interested by this feature too.

In my case I would definitively go with the Repo-wide config since the config would be the same for each uses of the repo, and allow different configurations per repo.

Regarding the validate_branch section, I would probably just require that the {ticket} is present since some organizations don't necessarily use folders in the feature branch name.
In my case here is what the .specify/config.json would look like:

[naming]
branch_format = "{ticket}" # e.g., PROJ-123
folder_format = "specs/{branch}" # keeps folder in lockstep with branch

Thanks for proposing this feature request.

[mattbrailsford]

We follow GitFlow standards too and I would very much like to see a configurable branch naming solution. I can’t justify changing our standards for the use of a third party tool so it would be much easier to encourage adoption within our company if I can make it follow our existing standards.