docs(core): SPECIFY_FEATURE sets the feature label, not the feature directory - #3786
Open
jawwad-ali wants to merge 1 commit into
Open
docs(core): SPECIFY_FEATURE sets the feature label, not the feature directory#3786jawwad-ali wants to merge 1 commit into
jawwad-ali wants to merge 1 commit into
Conversation
…irectory
docs/reference/core.md told users to set SPECIFY_FEATURE "to the feature
directory name ... to work on a specific feature when not using Git branches".
That does not work: SPECIFY_FEATURE only feeds get_current_branch /
Get-CurrentBranch (the feature *label*). The directory comes from
SPECIFY_FEATURE_DIRECTORY or .specify/feature.json.
Verified on main with the real helper -- with ONLY SPECIFY_FEATURE set:
$ SPECIFY_FEATURE=001-photo-albums ... get_feature_paths
ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or run
the specify command to create .specify/feature.json.
exit=1
$ SPECIFY_FEATURE_DIRECTORY=specs/001-photo-albums ... get_feature_paths
FEATURE_DIR -> <resolved>
CURRENT_BRANCH -> 001-photo-albums
The code's own error message points at the other variable, and the doc's own
"Two resolution axes" note directly below already says the feature is selected
by SPECIFY_FEATURE_DIRECTORY / .specify/feature.json -- so the table row
contradicted both the code and the paragraph under it.
Describe what the variable actually does, note that /speckit.specify and the
Git extension normally set it, and point at the directory axis. Docs only.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jawwad-ali
force-pushed
the
docs/specify-feature-is-a-label
branch
from
July 28, 2026 14:56
4f0dd70 to
60720ea
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Corrects documentation for feature-label and feature-directory resolution.
Changes:
- Clarifies
SPECIFY_FEATUREdoes not locate feature directories. - Documents the corresponding resolution error and alternatives.
Show a summary per file
| File | Description |
|---|---|
docs/reference/core.md |
Updates environment-variable documentation. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Medium
| | `SPECIFY_INIT_DIR` | Target a member project from outside its directory (e.g. a monorepo root) without `cd`, for non-interactive / CI use. Set it to the **project root** — the directory *containing* `.specify/` (relative paths resolve against the current directory). The path must exist and contain `.specify/`, otherwise the command errors and does **not** fall back to the current directory. Resolved once in the core root helper (`get_repo_root` in Bash, `Get-RepoRoot` in PowerShell), so it is honored by the core feature scripts (`/speckit.plan`, `/speckit.tasks`, …) and the Git extension's feature-branch creation, which inherit it. The `specify` CLI applies the **same** validation rules to every project-scoped subcommand (`specify integration …`, `specify extension …`, `specify workflow …`, `specify preset …`, and the rest that operate on a `.specify/` project), so those can target a member project too. When unset, Bash/PowerShell helpers keep their existing upward search; the `specify` CLI keeps its project-scoped resolver cwd-only unless a command explicitly defines broader detection (for example, bundle commands). | | ||
| | `SPECIFY_FEATURE_DIRECTORY` | Override the active feature directory *within* the resolved project (takes precedence over `.specify/feature.json`). Relative paths resolve under the project root. Combine with `SPECIFY_INIT_DIR` to pick both the project and the feature non-interactively. | | ||
| | `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches. Must be set in the context of the agent prior to using `/speckit.plan` or follow-up commands. | | ||
| | `SPECIFY_FEATURE` | Set the active feature **label** (e.g. `001-photo-albums`) — the value the core helpers report as the current feature/branch (`get_current_branch` in Bash, `Get-CurrentBranch` in PowerShell) when there is no Git branch context. Normally set for you by `/speckit.specify` (feature creation) and by the Git extension. It does **not** locate the feature directory on its own: with only `SPECIFY_FEATURE` set, `get_feature_paths` still fails with *"Feature directory not found. Set `SPECIFY_FEATURE_DIRECTORY` or run the specify command to create `.specify/feature.json`."* Use `SPECIFY_FEATURE_DIRECTORY` (above) or `.specify/feature.json` to select the directory. | |
mnriem
requested changes
Jul 28, 2026
mnriem
left a comment
mnriem
left a comment
Collaborator
There was a problem hiding this comment.
Please address Copilot feedback
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
docs/reference/core.md(Environment Variables table) tells users:That does not work.
SPECIFY_FEATUREonly feedsget_current_branch/Get-CurrentBranch— the feature label. The feature directory comes fromSPECIFY_FEATURE_DIRECTORYor.specify/feature.json.Verified on
mainwith the real helper:So a user following the doc gets a hard failure — and the code's own error message points at the other variable.
The doc also contradicts itself: the "Two resolution axes" note immediately below the table already states that
SPECIFY_FEATURE_DIRECTORY/.specify/feature.jsonselect the feature, with no mention ofSPECIFY_FEATURE.Fix
Describe what the variable actually does: it sets the active feature label reported by the core helpers when there is no Git branch context, it is normally set for you by
/speckit.specifyand the Git extension, and it does not locate the directory — with the real error message quoted, and a pointer to the directory axis.Docs only; no code change.
Verification
scripts/bash/common.sh(get_current_branch,get_feature_paths) and the PowerShell twin — I checked thatGet-CurrentBranchexists and reads$env:SPECIFY_FEATUREbefore naming it.markdownlint-cli2error count on this file is identical before and after (1 pre-existing, untouched by this diff).AI-assisted: authored with Claude Code. I ran both variables through the real
get_feature_pathsonmainto capture the exact failure before rewriting the row, rather than reasoning from the source alone.