[Bug]: Local config override file name differs between the docs (`<id>-config.local.yml`) and ConfigManager (`local-config.yml`)
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 72/100
Research direction
Read ConfigManager._get_local_config in src/specify_cli/extensions/__init__.py, then compare its expected filename with the user, API, and development guides and the ignore pattern in src/specify_cli/shared_infra.py. Use the reproduction script in the issue to confirm which filename applies; done when config overrides, hook conditions, git ignore behavior, and related removal or rescue handling agree with the chosen name.
Written by the indexing model from the issue text.
Description
Bug Description
The user-facing extension docs tell users to put local overrides in .specify/extensions/<id>/<id>-config.local.yml. ConfigManager._get_local_config reads .specify/extensions/<id>/local-config.yml instead (src/specify_cli/extensions/__init__.py:5350). A user who follows the guide gets no override, both in get_config() and in hook conditions such as config.x is set. The shared .specify/.gitignore only covers extensions/*/local-config.yml (src/specify_cli/shared_infra.py:33), so the documented file is also not ignored by git, although the guide says it is.
Either side could be the one to change. The code, design/extension.md:146 and shared_infra.py:33 use local-config.yml. These say <id>-config.local.yml:
extensions/EXTENSION-USER-GUIDE.md:351,361,377,910extensions/EXTENSION-API-REFERENCE.md:565,887extensions/EXTENSION-DEVELOPMENT-GUIDE.md:388
The remove, backup and rescue code also preserves *-config.local.yml (for example __init__.py:3523-3549).
Steps to Reproduce
Save this as repro.py and run uv run python -I repro.py from the repository root.
import os, tempfile
from pathlib import Path
from specify_cli.extensions import ConfigManager
proj = Path(tempfile.mkdtemp())
d = proj / ".specify/extensions/jira"
d.mkdir(parents=True)
(d / "jira-config.yml").write_text('project:\n key: "MSATS"\n')
(d / "jira-config.local.yml").write_text('project:\n key: "MYTEST"\n')
os.environ.pop("SPECKIT_JIRA_PROJECT_KEY", None)
print("with jira-config.local.yml: project.key =", ConfigManager(proj, "jira").get_value("project.key"))
(d / "jira-config.local.yml").rename(d / "local-config.yml")
print("with local-config.yml: project.key =", ConfigManager(proj, "jira").get_value("project.key"))
Expected Behavior
Per extensions/EXTENSION-USER-GUIDE.md:359-383, jira-config.local.yml overrides jira-config.yml, so project.key is MYTEST. If local-config.yml is the intended name, the user guide, API reference and development guide should say so.
Actual Behavior
with jira-config.local.yml: project.key = MSATS
with local-config.yml: project.key = MYTEST
Specify CLI Version
1.2.4.dev0 (main at 27d14e2)
AI Agent
Not applicable
Operating System
Linux 6.18 (Ubuntu container)
Python Version
Python 3.12.3
Additional Context
The docstring of ConfigManager itself (__init__.py:5267) names local-config.yml, so the code is at least consistent with itself and with the design document.
Also reproduced on macOS (Darwin 25.6, arm64) with Python 3.14.4 and uv run python -I repro.py against 27d14e2; the output matches the above.
AI Disclosure
Found and reproduced with Claude Code (model: Claude Opus 4.8), run autonomously under human supervision. The human reporter re-ran every reproduction above before filing.
- Dominant language
- Python
- Stars
- 147k
- Forks
- 13.2k
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 199
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github/spec-kit
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
[Bug]: `bundle init <bundle>` initialises with the default integration instead of the bundle's, then aborts with a clashPossibly taken @chelsealong claimed this 15 days ago. Opentriage-must-have
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
[Bug]: `specify preset set-priority` does not update agent command files that are already writtenPossibly taken @mikamikasuki claimed this 15 days ago. Opentriage-must-have
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
Maintainers usually reply within 1 day
-
[Bug]: Extension alias conflict check misses spellings that map to the same file, so one extension overwrites and then deletes another's aliasPossibly taken @chelsealong claimed this 13 days ago. Opentriage-must-have
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
bug-assess invalid triage-must-have
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
github/spec-kit#5080 · 1 comment ·
Maintainers usually reply within 1 day
Similar issues
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 2 days
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
cunla/fakeredis-py#636 ·
Maintainers usually reply within 2 days
-
namespace
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
EclipseFdn/open-vsx.org#15470 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
opensafely-core/job-server#6180 · 1 comment ·
Maintainers usually reply within 1 day
-
area:models enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day