{"record":{"id":"2df8d6d6f459ce51","repo":"github/spec-kit","slug":"unsupported-integration-type-normalized-type","errorCode":null,"errorMessage":"Unsupported integration type '{normalized_type}'. Use one of: {supported}.","messagePattern":"Unsupported integration type '(.+?)'\\. Use one of: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/integration_scaffold.py","lineNumber":213,"sourceCode":"    try:\n        target.parent.resolve().relative_to(root_resolved)\n    except (OSError, ValueError):\n        raise ValueError(\n            f\"Refusing to scaffold outside the repository root: {target}\"\n        ) from None\n\n\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()]","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/integration_scaffold.py#L195-L231","documentation":"scaffold_integration validates integration_type.strip().lower() against the _TEMPLATES map, whose keys are exactly 'markdown', 'toml', 'yaml', 'skills' (the values returned by supported_integration_scaffold_types()). Any other string aborts scaffolding before any file is touched. The message lists the accepted values so the fix is usually a one-word correction.","triggerScenarios":"Calling scaffold_integration with integration_type values like 'Markdown', 'md', 'python', 'goose', 'cli', or trailing junk ('markdown ') — note strip().lower() handles case and whitespace, so genuinely unknown words are the trigger; passing a registrar format or agent key instead of the template family also triggers it.","commonSituations":"Confusing the integration key (e.g. 'goose') with the template type (goose is 'yaml'); assuming a 'python' or 'custom' template exists because --script py exists; typos like 'tomal' or 'skill' (singular).","solutions":["Use one of the four supported types: markdown, toml, yaml, or skills — e.g. `markdown` for $ARGUMENTS-based agents, `yaml` for Goose-style recipes.","If unsure in code, derive the choices from the API: `from specify_cli.integration_scaffold import supported_integration_scaffold_types`.","Check for typos, extra characters, or passing the agent key instead of the base-class family."],"exampleFix":"# before\nscaffold_integration(root, \"my-agent\", \"md\")\n# after\nscaffold_integration(root, \"my-agent\", \"markdown\")","handlingStrategy":"validation","validationCode":"from specify_cli.integration_scaffold import supported_integration_scaffold_types\n\nITYPE = \"markdown\"\nassert ITYPE in supported_integration_scaffold_types(), (\n    f\"{ITYPE!r} not in {supported_integration_scaffold_types()}\"\n)","typeGuard":"from typing import Literal\n\nScaffoldType = Literal[\"markdown\", \"toml\", \"yaml\", \"skills\"]\n\ndef is_scaffold_type(value: str) -> bool:\n    return value in {\"markdown\", \"toml\", \"yaml\", \"skills\"}","tryCatchPattern":"try:\n    scaffold_integration(root, key, itype)\nexcept ValueError as exc:\n    if \"Unsupported integration type\" in str(exc):\n        itype = \"markdown\"  # or prompt the user with the listed options\n        scaffold_integration(root, key, itype)\n    else:\n        raise","preventionTips":["Source the accepted values from supported_integration_scaffold_types() instead of hard-coding them.","Use a Literal type for the integration_type parameter in calling code.","Remember the type is the base-class family (markdown/toml/yaml/skills), not the agent key."],"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"}