feat: support custom feature identifiers

[swbhollis]

Description

Spec Kit currently supports only sequential or timestamp-based prefixes for feature directories and Git branches. This enhancement adds support for a custom FEATURE_ID, supplied through the environment or script option.

Custom identifiers are validated, normalized to lowercase, and used consistently for feature directories and Git extension branches. Existing sequential and timestamp behavior remains unchanged.

Example: /speckit-specify FEATURE_ID=ENHANCEMENT-12345 Add project filtering and task search would create a folder within the spec directory called enhancement-12435-project-task-search.

Testing

• Tested locally with uv run specify --help: I followed the Local Development Guide, CLI direct feedback step with the new FEATURE_ID option. Also validated pre-existing projects with SpecKit already in-tact can leverage this extension capability as well.
• Ran existing tests with uv sync && uv run pytest
• [] Tested with a sample project (if applicable)

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

GitHub Copilot (GPT-5.6 Sol) assisted with reviewing, testing, and committing the implementation.

[mnriem]

Thanks for this — but the capability is largely already supported, and through mechanisms that keep Spec Kit's directory-based, Git-decoupled design intact:

• Custom feature-directory naming is already available via create-new-feature's --short-name <name>, and you can point a feature at any directory with SPECIFY_FEATURE_DIRECTORY or .specify/feature.json — the feature identifier is a document artifact, not tied to Git.

• Custom Git branch naming belongs to the git extension (or you create the branch yourself). Threading a core FEATURE_ID into the git extension's branch scripts re-couples core to Git, which is the dependence we deliberately removed.

So a custom identifier that names the directory is already doable today, and branch naming is the git extension's concern. Closing as covered by existing functionality — but if there's a specific gap --short-name + SPECIFY_FEATURE_DIRECTORY don't cover, please reopen with that case and we'll look.

[swbhollis]

Hi @mnriem ,

I appreciate your response! I'm not entirely following. If we run /speckit-specify Add project filtering and task search, it would create a folder within the spec directory called 001-project-task-search. How can the developer have this folder set with the work id without changing any of the underlying skills included with spec-kit, or needing to manually update the folder itself?

Are you suggesting creating a .specify/extension and associated skill for this purpose? Just trying to make sure I understand.

Update: I tried out the spec-kit-branch-convention extension, though this doesn't seem to update the branch / folder names when I run a specify. From this thread: #407

I see you commented the following:

We are going to separate GIt branching and naming into an extension as an opt in. And the folder naming will be separated from that.

Any idea how to opt in?

[mnriem]

Hi @swbhollis — good questions, and the short answer is: no skill changes or manual folder edits needed. The specs folder name is controlled by SPECIFY_FEATURE_DIRECTORY, and the built-in /speckit.specify already honors it as-is when you provide it. Its resolution order is:

1. If you've explicitly set SPECIFY_FEATURE_DIRECTORY (env var, argument, or config), it uses that exactly — e.g. specs/JIRA-1234-project-task-search.

2. Otherwise it auto-generates <prefix>-<short-name> (e.g. 001-project-task-search), where the prefix comes from your init-options.json numbering.

So to put your own work id on the folder, set it before running specify:

Plain text

export SPECIFY_FEATURE_DIRECTORY=specs/JIRA-1234-project-task-search

then run /speckit.specify Add project filtering and task search — it'll use that folder verbatim, persist it to .specify/feature.json, and every later command (plan, tasks, …) will keep using that same folder. The stock skills stay untouched.

If you only want to control the slug (not the whole path), create-new-feature also takes --short-name, producing <prefix>-<your-short-name>.

On the branch-convention extension: that one governs branch naming, which is deliberately separate from folder naming (the #407 split you quoted), so it won't rename the specs folder — SPECIFY_FEATURE_DIRECTORY / --short-name are the folder levers.

That's why I closed #4500 as already-addressed rather than a rejection — the capability is already there, just via the env var / short-name rather than a new identifier field. Happy to clarify further if that doesn't match what you're seeing.

[swbhollis]

Thanks @mnriem! So a developer would need to run this export command prior to every specify for each spec? For example, if the developer works on JIRA-5678 next, they'd have to run export SPECIFY_FEATURE_DIRECTORY=specs/JIRA-5678-project-task-delete, prior to the specify? This PR had simplified that experience with just including FEATURE_ID as part of the specify itself for what it's worth. I'm trying to keep the steps as small as possible for developers juggling multiple enhancements / specs.