{"record":{"id":"141e9536a9a2daaa","repo":"github/spec-kit","slug":"refusing-to-overwrite-existing-scaffold-file-s","errorCode":null,"errorMessage":"Refusing to overwrite existing scaffold file(s): {labels}","messagePattern":"Refusing to overwrite existing scaffold file\\(s\\): (.+?)","errorType":"validation","errorClass":"FileExistsError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/integration_scaffold.py","lineNumber":234,"sourceCode":"\n    integrations_root = project_root / \"src\" / \"specify_cli\" / \"integrations\"\n    tests_root = project_root / \"tests\" / \"integrations\"\n    if not _is_spec_kit_repo_root(project_root):\n        raise ValueError(\"Run this command from the Spec Kit repository root.\")\n\n    package_name = _package_name(clean_key)\n    class_name = _class_name(clean_key)\n    integration_dir = integrations_root / package_name\n    integration_file = integration_dir / \"__init__.py\"\n    test_file = tests_root / f\"test_integration_{package_name}.py\"\n\n    for target in (integration_file, test_file):\n        _assert_safe_scaffold_target(project_root, target)\n\n    existing = [path for path in (integration_file, test_file) if path.exists()]\n    if existing:\n        labels = \", \".join(path.relative_to(project_root).as_posix() for path in existing)\n        raise FileExistsError(f\"Refusing to overwrite existing scaffold file(s): {labels}\")\n\n    created_integration_dir = not integration_dir.exists()\n    try:\n        integration_dir.mkdir(exist_ok=True)\n        integration_file.write_text(\n            _integration_content(\n                key=clean_key,\n                class_name=class_name,\n                integration_type=normalized_type,\n            ),\n            encoding=\"utf-8\",\n        )\n        test_file.write_text(\n            _test_content(\n                key=clean_key,\n                class_name=class_name,\n                integration_type=normalized_type,\n            ),","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/integration_scaffold.py#L216-L252","documentation":"scaffold_integration is intentionally non-destructive: before writing the new package's __init__.py and tests/integrations/test_integration_<pkg>.py it checks whether either file already exists, and raises FileExistsError (a distinct type from the ValueError guards) listing the offending relative paths. This protects hand-written or previously scaffolded integrations from being overwritten.","triggerScenarios":"Running the scaffold twice with the same key; scaffolding a key whose package already exists (e.g. re-running 'specify init'-era scaffold for 'gemini'); an existing test file named test_integration_<package_name>.py colliding even when the package dir is new.","commonSituations":"Re-running a scaffold command after a partial earlier run; two agents whose keys normalize to the same package_name (hyphens to underscores); forgetting a previous experiment with the same key exists.","solutions":["Choose a different, unique integration key for the new agent.","If the previous files are disposable, delete or rename the files listed in the error message and re-run the scaffold.","If the existing integration is real work, edit it in place rather than re-scaffolding."],"exampleFix":"# before\nValueError/FileExistsError: Refusing to overwrite existing scaffold file(s): src/specify_cli/integrations/my_agent/__init__.py\n# after\n$ git rm src/specify_cli/integrations/my_agent/__init__.py tests/integrations/test_integration_my_agent.py\n# then re-run scaffold","handlingStrategy":"try-catch","validationCode":"pkg = key.replace(\"-\", \"_\")\npaths = [\n    root / \"src\" / \"specify_cli\" / \"integrations\" / pkg / \"__init__.py\",\n    root / \"tests\" / \"integrations\" / f\"test_integration_{pkg}.py\",\n]\nif any(p.exists() for p in paths):\n    raise SystemExit(f\"scaffold files already exist: {[str(p) for p in paths if p.exists()]}\")","typeGuard":null,"tryCatchPattern":"try:\n    scaffold_integration(root, key, itype)\nexcept FileExistsError as exc:\n    print(str(exc))  # lists existing files; pick a new key or remove them deliberately","preventionTips":["Check for the two target files before scaffolding (package __init__.py and test file).","Use unique kebab-case agent keys per integration.","Treat the FileExistsError as intentional protection; never blind-delete files to silence it."],"tags":["filesystem","scaffold","idempotency"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}