{"record":{"id":"944b84f45d9c6fd1","repo":"github/spec-kit","slug":"run-this-command-from-the-spec-kit-repository-root","errorCode":null,"errorMessage":"Run this command from the Spec Kit repository root.","messagePattern":"Run this command from the Spec Kit repository root\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/integration_scaffold.py","lineNumber":220,"sourceCode":"\ndef scaffold_integration(\n    project_root: Path,\n    key: str,\n    integration_type: str,\n) -> IntegrationScaffoldResult:\n    \"\"\"Create a minimal built-in integration package and test skeleton.\"\"\"\n    clean_key = _clean_key(key)\n    normalized_type = integration_type.strip().lower()\n    if normalized_type not in _TEMPLATES:\n        supported = \", \".join(supported_integration_scaffold_types())\n        raise ValueError(\n            f\"Unsupported integration type '{normalized_type}'. Use one of: {supported}.\"\n        )\n\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)","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/integration_scaffold.py#L202-L238","documentation":"scaffold_integration is a maintainer tool: it generates files under src/specify_cli/integrations/ and tests/integrations/ inside the Spec Kit source repository itself. Before writing, it verifies the layout with _is_spec_kit_repo_root(project_root) and refuses otherwise. This error means the supplied project root does not look like the Spec Kit repo checkout.","triggerScenarios":"Calling scaffold_integration with a user project directory (a project created by `specify init`) instead of a clone of the spec-kit repository; running from a random directory where the src/specify_cli package layout is absent.","commonSituations":"Users running the scaffold command inside their own app project, expecting it to add a custom integration there (it cannot — it only generates files in the Spec Kit source tree); wrong cwd when invoking the CLI.","solutions":["Clone github/spec-kit (or your fork), and run the scaffold command from that repository root.","If adding a personal integration to an existing project, write the integration package by hand under src/specify_cli/integrations/ following AGENTS.md's Quickstart, instead of scaffolding outside the repo.","Verify the root with a quick check: `ls src/specify_cli/integrations tests/integrations` succeeds only in the real repo."],"exampleFix":"# before (inside a user project)\n$ cd ~/my-app && specify ... scaffold my-agent markdown\n# after (inside the spec-kit clone)\n$ cd ~/src/spec-kit && # run scaffold here","handlingStrategy":"type-guard","validationCode":"from pathlib import Path\n\ndef is_spec_kit_repo(root: Path) -> bool:\n    return (root / \"src\" / \"specify_cli\" / \"integrations\").is_dir() and \\\n           (root / \"tests\" / \"integrations\").is_dir()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only run the scaffold tool inside a clone/fork of the spec-kit repository.","Wrap invocations with a cheap layout check (src/specify_cli and tests/integrations exist).","For user projects, remember scaffolding custom integrations there is unsupported by design."],"tags":["validation","scaffold","developer-error"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}